BackgroundFileSaver.h (12725B)
1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2 /* vim: set ts=2 et sw=2 tw=80: */ 3 /* This Source Code Form is subject to the terms of the Mozilla Public 4 * License, v. 2.0. If a copy of the MPL was not distributed with this 5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 6 7 /** 8 * This file defines two implementations of the nsIBackgroundFileSaver 9 * interface. See the "test_backgroundfilesaver.js" file for usage examples. 10 */ 11 12 #ifndef BackgroundFileSaver_h__ 13 #define BackgroundFileSaver_h__ 14 15 #include "ScopedNSSTypes.h" 16 #include "mozilla/Mutex.h" 17 #include "nsCOMArray.h" 18 #include "nsCOMPtr.h" 19 #include "nsIAsyncOutputStream.h" 20 #include "nsIBackgroundFileSaver.h" 21 #include "nsIStreamListener.h" 22 #include "nsStreamUtils.h" 23 #include "nsString.h" 24 25 class nsIAsyncInputStream; 26 class nsISerialEventTarget; 27 28 namespace mozilla { 29 namespace net { 30 31 class DigestOutputStream; 32 33 //////////////////////////////////////////////////////////////////////////////// 34 //// BackgroundFileSaver 35 36 class BackgroundFileSaver : public nsIBackgroundFileSaver { 37 public: 38 NS_DECL_NSIBACKGROUNDFILESAVER 39 40 BackgroundFileSaver(); 41 42 /** 43 * Initializes the pipe and the worker thread on XPCOM construction. 44 * 45 * This is called automatically by the XPCOM infrastructure, and if this 46 * fails, the factory will delete this object without returning a reference. 47 */ 48 nsresult Init(); 49 50 /** 51 * Number of worker threads that are currently running. 52 */ 53 static uint32_t sThreadCount; 54 55 /** 56 * Maximum number of worker threads reached during the current download 57 * session, used for telemetry. 58 * 59 * When there are no more worker threads running, we consider the download 60 * session finished, and this counter is reset. 61 */ 62 static uint32_t sTelemetryMaxThreadCount; 63 64 protected: 65 virtual ~BackgroundFileSaver(); 66 67 /** 68 * Thread that constructed this object. 69 */ 70 nsCOMPtr<nsIEventTarget> mControlEventTarget; 71 72 /** 73 * Thread to which the actual input/output is delegated. 74 */ 75 nsCOMPtr<nsISerialEventTarget> mBackgroundET; 76 77 /** 78 * Stream that receives data from derived classes. The received data will be 79 * available to the worker thread through mPipeInputStream. This is an 80 * instance of nsPipeOutputStream, not BackgroundFileSaverOutputStream. 81 */ 82 nsCOMPtr<nsIAsyncOutputStream> mPipeOutputStream; 83 84 /** 85 * Used during initialization, determines if the pipe is created with an 86 * infinite buffer. An infinite buffer is required if the derived class 87 * implements nsIStreamListener, because this interface requires all the 88 * provided data to be consumed synchronously. 89 */ 90 virtual bool HasInfiniteBuffer() = 0; 91 92 /** 93 * Used by derived classes if they need to be called back while copying. 94 */ 95 virtual nsAsyncCopyProgressFun GetProgressCallback() = 0; 96 97 /** 98 * Stream used by the worker thread to read the data to be saved. 99 */ 100 nsCOMPtr<nsIAsyncInputStream> mPipeInputStream; 101 102 private: 103 friend class NotifyTargetChangeRunnable; 104 105 /** 106 * Matches the nsIBackgroundFileSaver::observer property. 107 * 108 * @remarks This is a strong reference so that JavaScript callers don't need 109 * to worry about keeping another reference to the observer. 110 */ 111 nsCOMPtr<nsIBackgroundFileSaverObserver> mObserver; 112 113 ////////////////////////////////////////////////////////////////////////////// 114 //// Shared state between control and worker threads 115 116 /** 117 * Protects the shared state between control and worker threads. This mutex 118 * is always locked for a very short time, never during input/output. 119 */ 120 mozilla::Mutex mLock{"BackgroundFileSaver.mLock"}; 121 122 /** 123 * True if the worker thread is already waiting to process a change in state. 124 */ 125 bool mWorkerThreadAttentionRequested MOZ_GUARDED_BY(mLock){false}; 126 127 /** 128 * True if the operation should finish as soon as possibile. 129 */ 130 bool mFinishRequested MOZ_GUARDED_BY(mLock){false}; 131 132 /** 133 * True if the operation completed, with either success or failure. 134 */ 135 bool mComplete MOZ_GUARDED_BY(mLock){false}; 136 137 /** 138 * Holds the current file saver status. This is a success status while the 139 * object is working correctly, and remains such if the operation completes 140 * successfully. This becomes an error status when an error occurs on the 141 * worker thread, or when the operation is canceled. 142 */ 143 nsresult mStatus MOZ_GUARDED_BY(mLock){NS_OK}; 144 145 /** 146 * True if we should append data to the initial target file, instead of 147 * overwriting it. 148 */ 149 bool mAppend MOZ_GUARDED_BY(mLock){false}; 150 151 /** 152 * This is set by the first SetTarget call on the control thread, and contains 153 * the target file name that will be used by the worker thread, as soon as it 154 * is possible to update mActualTarget and open the file. This is null if no 155 * target was ever assigned to this object. 156 */ 157 nsCOMPtr<nsIFile> mInitialTarget MOZ_GUARDED_BY(mLock); 158 159 /** 160 * This is set by the first SetTarget call on the control thread, and 161 * indicates whether mInitialTarget should be kept as partially completed, 162 * rather than deleted, if the operation fails or is canceled. 163 */ 164 bool mInitialTargetKeepPartial MOZ_GUARDED_BY(mLock){false}; 165 166 /** 167 * This is set by subsequent SetTarget calls on the control thread, and 168 * contains the new target file name to which the worker thread will move the 169 * target file, as soon as it can be done. This is null if SetTarget was 170 * called only once, or no target was ever assigned to this object. 171 * 172 * The target file can be renamed multiple times, though only the most recent 173 * rename is guaranteed to be processed by the worker thread. 174 */ 175 nsCOMPtr<nsIFile> mRenamedTarget MOZ_GUARDED_BY(mLock); 176 177 /** 178 * This is set by subsequent SetTarget calls on the control thread, and 179 * indicates whether mRenamedTarget should be kept as partially completed, 180 * rather than deleted, if the operation fails or is canceled. 181 */ 182 bool mRenamedTargetKeepPartial MOZ_GUARDED_BY(mLock){false}; 183 184 /** 185 * While NS_AsyncCopy is in progress, allows canceling it. Null otherwise. 186 * This is read by both threads but only written by the worker thread. 187 */ 188 nsCOMPtr<nsISupports> mAsyncCopyContext MOZ_GUARDED_BY(mLock); 189 190 /** 191 * The SHA 256 hash in raw bytes of the downloaded file. This is written 192 * by the worker thread but can be read on the main thread. 193 */ 194 nsCString mSha256 MOZ_GUARDED_BY(mLock); 195 196 /** 197 * Whether or not to compute the hash. Must be set on the main thread before 198 * setTarget is called. 199 */ 200 bool mSha256Enabled MOZ_GUARDED_BY(mLock){false}; 201 202 /** 203 * Store the signature info. 204 */ 205 nsTArray<nsTArray<nsTArray<uint8_t>>> mSignatureInfo MOZ_GUARDED_BY(mLock); 206 207 /** 208 * Whether or not to extract the signature. Must be set on the main thread 209 * before setTarget is called. 210 */ 211 bool mSignatureInfoEnabled MOZ_GUARDED_BY(mLock){false}; 212 213 ////////////////////////////////////////////////////////////////////////////// 214 //// State handled exclusively by the worker thread 215 216 /** 217 * Current target file associated to the input and output streams. 218 */ 219 nsCOMPtr<nsIFile> mActualTarget; 220 221 /** 222 * Indicates whether mActualTarget should be kept as partially completed, 223 * rather than deleted, if the operation fails or is canceled. 224 */ 225 bool mActualTargetKeepPartial{false}; 226 227 /** 228 * Used to calculate the file hash. This keeps state across file renames and 229 * is lazily initialized in ProcessStateChange. 230 */ 231 Maybe<Digest> mDigest; 232 233 ////////////////////////////////////////////////////////////////////////////// 234 //// Private methods 235 236 /** 237 * Called when NS_AsyncCopy completes. 238 * 239 * @param aClosure 240 * Populated with a raw pointer to the BackgroundFileSaver object. 241 * @param aStatus 242 * Success or failure status specified when the copy was interrupted. 243 */ 244 static void AsyncCopyCallback(void* aClosure, nsresult aStatus); 245 246 /** 247 * Called on the control thread after state changes, to ensure that the worker 248 * thread will process the state change appropriately. 249 * 250 * @param aShouldInterruptCopy 251 * If true, the current NS_AsyncCopy, if any, is canceled. 252 */ 253 nsresult GetWorkerThreadAttention(bool aShouldInterruptCopy); 254 255 /** 256 * Event called on the worker thread to begin processing a state change. 257 */ 258 nsresult ProcessAttention(); 259 260 /** 261 * Called by ProcessAttention to execute the operations corresponding to the 262 * state change. If this results in an error, ProcessAttention will force the 263 * entire operation to be aborted. 264 */ 265 nsresult ProcessStateChange(); 266 267 /** 268 * Returns true if completion conditions are met on the worker thread. The 269 * first time this happens, posts the completion event to the control thread. 270 */ 271 bool CheckCompletion(); 272 273 /** 274 * Event called on the control thread to indicate that file contents will now 275 * be saved to the specified file. 276 */ 277 nsresult NotifyTargetChange(nsIFile* aTarget); 278 279 /** 280 * Event called on the control thread to send the final notification. 281 */ 282 nsresult NotifySaveComplete(); 283 284 /** 285 * Verifies the signature of the binary at the specified file path and stores 286 * the signature data in mSignatureInfo. We extract only X.509 certificates, 287 * since that is what Google's Safebrowsing protocol specifies. 288 */ 289 nsresult ExtractSignatureInfo(const nsAString& filePath); 290 }; 291 292 //////////////////////////////////////////////////////////////////////////////// 293 //// BackgroundFileSaverOutputStream 294 295 class BackgroundFileSaverOutputStream : public BackgroundFileSaver, 296 public nsIAsyncOutputStream, 297 public nsIOutputStreamCallback { 298 public: 299 NS_DECL_THREADSAFE_ISUPPORTS 300 NS_DECL_NSIOUTPUTSTREAM 301 NS_DECL_NSIASYNCOUTPUTSTREAM 302 NS_DECL_NSIOUTPUTSTREAMCALLBACK 303 304 BackgroundFileSaverOutputStream(); 305 306 protected: 307 virtual bool HasInfiniteBuffer() override; 308 virtual nsAsyncCopyProgressFun GetProgressCallback() override; 309 310 private: 311 ~BackgroundFileSaverOutputStream() = default; 312 313 /** 314 * Original callback provided to our AsyncWait wrapper. 315 */ 316 nsCOMPtr<nsIOutputStreamCallback> mAsyncWaitCallback; 317 }; 318 319 //////////////////////////////////////////////////////////////////////////////// 320 //// BackgroundFileSaverStreamListener. This class is instantiated by 321 // nsExternalHelperAppService, DownloadCore.sys.mjs, and possibly others. 322 323 class BackgroundFileSaverStreamListener final : public BackgroundFileSaver, 324 public nsIStreamListener { 325 public: 326 NS_DECL_THREADSAFE_ISUPPORTS 327 NS_DECL_NSIREQUESTOBSERVER 328 NS_DECL_NSISTREAMLISTENER 329 330 BackgroundFileSaverStreamListener() = default; 331 332 protected: 333 virtual bool HasInfiniteBuffer() override; 334 virtual nsAsyncCopyProgressFun GetProgressCallback() override; 335 336 private: 337 ~BackgroundFileSaverStreamListener() = default; 338 339 /** 340 * Protects the state related to whether the request should be suspended. 341 */ 342 mozilla::Mutex mSuspensionLock{ 343 "BackgroundFileSaverStreamListener.mSuspensionLock"}; 344 345 /** 346 * Whether we should suspend the request because we received too much data. 347 */ 348 bool mReceivedTooMuchData MOZ_GUARDED_BY(mSuspensionLock){false}; 349 350 /** 351 * Request for which we received too much data. This is populated when 352 * mReceivedTooMuchData becomes true for the first time. 353 */ 354 nsCOMPtr<nsIRequest> mRequest MOZ_GUARDED_BY(mSuspensionLock); 355 356 /** 357 * Whether mRequest is currently suspended. 358 */ 359 bool mRequestSuspended MOZ_GUARDED_BY(mSuspensionLock){false}; 360 361 /** 362 * Called while NS_AsyncCopy is copying data. 363 */ 364 static void AsyncCopyProgressCallback(void* aClosure, uint32_t aCount); 365 366 /** 367 * Called on the control thread to suspend or resume the request. 368 */ 369 nsresult NotifySuspendOrResume(); 370 }; 371 372 // A wrapper around nsIOutputStream, so that we can compute hashes on the 373 // stream without copying and without polluting pristine NSS code with XPCOM 374 // interfaces. 375 class DigestOutputStream : public nsIOutputStream { 376 public: 377 NS_DECL_THREADSAFE_ISUPPORTS 378 NS_DECL_NSIOUTPUTSTREAM 379 // Constructor. Neither parameter may be null. The caller owns both. 380 DigestOutputStream(nsIOutputStream* aStream, Digest& aDigest); 381 382 private: 383 virtual ~DigestOutputStream() = default; 384 385 // Calls to write are passed to this stream. 386 nsCOMPtr<nsIOutputStream> mOutputStream; 387 // Digest used to compute the hash, owned by the caller. 388 Digest& mDigest; 389 390 // Don't accidentally copy construct. 391 DigestOutputStream(const DigestOutputStream& d) = delete; 392 }; 393 394 } // namespace net 395 } // namespace mozilla 396 397 #endif