tor-browser

Promise.h (21064B)

---

/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set ts=8 sts=2 et sw=2 tw=80: */
/* 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/. */

#ifndef mozilla_dom_Promise_h
#define mozilla_dom_Promise_h

#include <functional>
#include <type_traits>
#include <utility>

#include "ErrorList.h"
#include "js/RootingAPI.h"
#include "js/TypeDecls.h"
#include "mozilla/AlreadyAddRefed.h"
#include "mozilla/Assertions.h"
#include "mozilla/ErrorResult.h"
#include "mozilla/HoldDropJSObjects.h"
#include "mozilla/RefPtr.h"
#include "mozilla/Result.h"
#include "mozilla/WeakPtr.h"
#include "mozilla/dom/AutoEntryScript.h"
#include "mozilla/dom/ScriptSettings.h"
#include "mozilla/dom/ToJSValue.h"
#include "nsCycleCollectionParticipant.h"
#include "nsError.h"
#include "nsISupports.h"
#include "nsString.h"

class nsCycleCollectionTraversalCallback;
class nsIGlobalObject;

namespace JS {
class Value;
}

namespace mozilla::webgpu {
class PipelineError;
}

namespace mozilla::dom {

class AnyCallback;
class MediaStreamError;
class PromiseInit;
class PromiseNativeHandler;
class PromiseDebugging;

class Promise : public SupportsWeakPtr, public JSHolderBase {
 friend class PromiseTask;
 friend class PromiseWorkerProxy;
 friend class PromiseWorkerProxyRunnable;

public:
 NS_INLINE_DECL_CYCLE_COLLECTING_NATIVE_REFCOUNTING(Promise)
 NS_DECL_CYCLE_COLLECTION_SCRIPT_HOLDER_NATIVE_CLASS(Promise)

 enum PropagateUserInteraction {
   eDontPropagateUserInteraction,
   ePropagateUserInteraction
 };

 // Promise creation tries to create a JS reflector for the Promise, so is
 // fallible.  Furthermore, we don't want to do JS-wrapping on a 0-refcount
 // object, so we addref before doing that and return the addrefed pointer
 // here.
 // Pass ePropagateUserInteraction for aPropagateUserInteraction if you want
 // the promise resolve handler to be called as if we were handling user
 // input events in case we are currently handling user input events.
 static already_AddRefed<Promise> Create(
     nsIGlobalObject* aGlobal, ErrorResult& aRv,
     PropagateUserInteraction aPropagateUserInteraction =
         eDontPropagateUserInteraction);

 // Same as Promise::Create but never throws, but instead:
 // 1. Causes crash on OOM (as nearly every other web APIs do)
 // 2. Silently creates a no-op Promise if the JS context is shut down
 // This can be useful for implementations that produce promises but do not
 // care whether the current global is alive to consume them.
 // Note that PromiseObj() can return a nullptr if created this way.
 static already_AddRefed<Promise> CreateInfallible(
     nsIGlobalObject* aGlobal,
     PropagateUserInteraction aPropagateUserInteraction =
         eDontPropagateUserInteraction);

 // Reports a rejected Promise by sending an error report.
 static void ReportRejectedPromise(JSContext* aCx,
                                   JS::Handle<JSObject*> aPromise);

 using MaybeFunc = void (Promise::*)(JSContext*, JS::Handle<JS::Value>);

 // Helpers for using Promise from C++.
 // Most DOM objects are handled already.  To add a new type T, add a
 // ToJSValue overload in ToJSValue.h.
 // aArg is a const reference so we can pass rvalues like integer constants
 template <typename T>
 void MaybeResolve(T&& aArg) {
   MaybeSomething(std::forward<T>(aArg), &Promise::MaybeResolve);
 }

 void MaybeResolveWithUndefined();

 void MaybeReject(JS::Handle<JS::Value> aValue) {
   MaybeSomething(aValue, &Promise::MaybeReject);
 }

 // This method is deprecated.  Consumers should MaybeRejectWithDOMException if
 // they are rejecting with a DOMException, or use one of the other
 // MaybeReject* methods otherwise.  If they have a random nsresult which may
 // or may not correspond to a DOMException type, they should consider using an
 // appropriate DOMException-type nsresult with an informative message and
 // calling MaybeRejectWithDOMException.
 inline void MaybeReject(nsresult aArg) {
   MOZ_ASSERT(NS_FAILED(aArg));
   MaybeSomething(aArg, &Promise::MaybeReject);
 }

 inline void MaybeReject(ErrorResult&& aArg) {
   MOZ_ASSERT(aArg.Failed());
   MaybeSomething(std::move(aArg), &Promise::MaybeReject);
   // That should have consumed aArg.
   MOZ_ASSERT(!aArg.Failed());
 }

 void MaybeReject(const RefPtr<MediaStreamError>& aArg);
 void MaybeReject(const RefPtr<webgpu::PipelineError>& aArg);

 void MaybeRejectWithUndefined();

 void MaybeResolveWithClone(JSContext* aCx, JS::Handle<JS::Value> aValue);
 void MaybeRejectWithClone(JSContext* aCx, JS::Handle<JS::Value> aValue);

 // Facilities for rejecting with various spec-defined exception values.
#define DOMEXCEPTION(name, err)                                   \
 inline void MaybeRejectWith##name(const nsACString& aMessage) { \
   ErrorResult res;                                              \
   res.Throw##name(aMessage);                                    \
   MaybeReject(std::move(res));                                  \
 }                                                               \
 template <int N>                                                \
 void MaybeRejectWith##name(const char(&aMessage)[N]) {          \
   MaybeRejectWith##name(nsLiteralCString(aMessage));            \
 }

#include "mozilla/dom/DOMExceptionNames.h"

#undef DOMEXCEPTION

 template <ErrNum errorNumber, typename... Ts>
 void MaybeRejectWithTypeError(Ts&&... aMessageArgs) {
   ErrorResult res;
   res.ThrowTypeError<errorNumber>(std::forward<Ts>(aMessageArgs)...);
   MaybeReject(std::move(res));
 }

 inline void MaybeRejectWithTypeError(const nsACString& aMessage) {
   ErrorResult res;
   res.ThrowTypeError(aMessage);
   MaybeReject(std::move(res));
 }

 template <int N>
 void MaybeRejectWithTypeError(const char (&aMessage)[N]) {
   MaybeRejectWithTypeError(nsLiteralCString(aMessage));
 }

 template <ErrNum errorNumber, typename... Ts>
 void MaybeRejectWithRangeError(Ts&&... aMessageArgs) {
   ErrorResult res;
   res.ThrowRangeError<errorNumber>(std::forward<Ts>(aMessageArgs)...);
   MaybeReject(std::move(res));
 }

 inline void MaybeRejectWithRangeError(const nsACString& aMessage) {
   ErrorResult res;
   res.ThrowRangeError(aMessage);
   MaybeReject(std::move(res));
 }

 template <int N>
 void MaybeRejectWithRangeError(const char (&aMessage)[N]) {
   MaybeRejectWithRangeError(nsLiteralCString(aMessage));
 }

 // DO NOT USE MaybeRejectBrokenly with in new code.  Promises should be
 // rejected with Error instances.
 // Note: MaybeRejectBrokenly is a template so we can use it with DOMException
 // without instantiating the DOMException specialization of MaybeSomething in
 // every translation unit that includes this header, because that would
 // require use to include DOMException.h either here or in all those
 // translation units.
 template <typename T>
 void MaybeRejectBrokenly(const T& aArg);  // Not implemented by default; see
                                           // specializations in the .cpp for
                                           // the T values we support.

 // If the JSContext has a pending exception then this will reject the promise
 // with that exception and clear it from the JSContext.
 void MaybeRejectWithExceptionFromContext(JSContext* aCx) {
   HandleException(aCx);
 }

 // Mark a settled promise as already handled so that rejections will not
 // be reported as unhandled.
 bool SetSettledPromiseIsHandled();

 // Mark a promise as handled so that rejections will not be reported as
 // unhandled. Consider using SetSettledPromiseIsHandled if this promise is
 // expected to be settled.
 [[nodiscard]] bool SetAnyPromiseIsHandled();

 // WebIDL

 nsIGlobalObject* GetParentObject() const { return GetGlobalObject(); }

 // Do the equivalent of Promise.resolve in the compartment of aGlobal.  The
 // compartment of aCx is ignored.  Errors are reported on the ErrorResult; if
 // aRv comes back !Failed(), this function MUST return a non-null value.
 // Pass ePropagateUserInteraction for aPropagateUserInteraction if you want
 // the promise resolve handler to be called as if we were handling user
 // input events in case we are currently handling user input events.
 static already_AddRefed<Promise> Resolve(
     nsIGlobalObject* aGlobal, JSContext* aCx, JS::Handle<JS::Value> aValue,
     ErrorResult& aRv,
     PropagateUserInteraction aPropagateUserInteraction =
         eDontPropagateUserInteraction);

 // Do the equivalent of Promise.resolve in the compartment of aGlobal.
 // The promise is resolved with the JS value corresponding to aValue.
 // If this fails, the promise is rejected with the exception.
 template <typename T>
 static already_AddRefed<Promise> Resolve(
     nsIGlobalObject* aGlobal, T&& aValue, ErrorResult& aError,
     PropagateUserInteraction aPropagateUserInteraction =
         eDontPropagateUserInteraction) {
   AutoJSAPI jsapi;
   if (!jsapi.Init(aGlobal)) {
     aError.Throw(NS_ERROR_UNEXPECTED);
     return nullptr;
   }

   JSContext* cx = jsapi.cx();
   JS::Rooted<JS::Value> val(cx);
   if (!ToJSValue(cx, std::forward<T>(aValue), &val)) {
     return Promise::RejectWithExceptionFromContext(aGlobal, cx, aError);
   }

   return Resolve(aGlobal, cx, val, aError, aPropagateUserInteraction);
 }

 // Do the equivalent of Promise.reject in the compartment of aGlobal.  The
 // compartment of aCx is ignored.  Errors are reported on the ErrorResult; if
 // aRv comes back !Failed(), this function MUST return a non-null value.
 static already_AddRefed<Promise> Reject(nsIGlobalObject* aGlobal,
                                         JSContext* aCx,
                                         JS::Handle<JS::Value> aValue,
                                         ErrorResult& aRv);

 template <typename T>
 static already_AddRefed<Promise> Reject(nsIGlobalObject* aGlobal, T&& aValue,
                                         ErrorResult& aError) {
   AutoJSAPI jsapi;
   if (!jsapi.Init(aGlobal)) {
     aError.Throw(NS_ERROR_UNEXPECTED);
     return nullptr;
   }

   JSContext* cx = jsapi.cx();
   JS::Rooted<JS::Value> val(cx);
   if (!ToJSValue(cx, std::forward<T>(aValue), &val)) {
     return Promise::RejectWithExceptionFromContext(aGlobal, cx, aError);
   }

   return Reject(aGlobal, cx, val, aError);
 }

 static already_AddRefed<Promise> RejectWithExceptionFromContext(
     nsIGlobalObject* aGlobal, JSContext* aCx, ErrorResult& aError);

 // Do the equivalent of Promise.all in the current compartment of aCx.  Errors
 // are reported on the ErrorResult; if aRv comes back !Failed(), this function
 // MUST return a non-null value.
 // Pass ePropagateUserInteraction for aPropagateUserInteraction if you want
 // the promise resolve handler to be called as if we were handling user
 // input events in case we are currently handling user input events.
 static already_AddRefed<Promise> All(
     JSContext* aCx, const nsTArray<RefPtr<Promise>>& aPromiseList,
     ErrorResult& aRv,
     PropagateUserInteraction aPropagateUserInteraction =
         eDontPropagateUserInteraction);

 using SuccessSteps =
     const std::function<void(const Span<JS::Heap<JS::Value>>&)>&;
 using FailureSteps = const std::function<void(JS::Handle<JS::Value>)>&;
 // Wait for all aPromises' results, calling either aFailureSteps if any
 // promise rejects, or aSuccessSteps if all promises resolves.
 // aCycleCollectedArg can be passed to keep state alive while waiting for the
 // promises, making sure that it's cycle collected.
 MOZ_CAN_RUN_SCRIPT
 static void WaitForAll(nsIGlobalObject* aGlobal,
                        const Span<RefPtr<Promise>>& aPromises,
                        SuccessSteps aSuccessSteps, FailureSteps aFailureSteps,
                        nsISupports* aCycleCollectedArg = nullptr);

 template <typename Callback, typename... Args>
 using IsHandlerCallback =
     std::is_same<already_AddRefed<Promise>,
                  decltype(std::declval<Callback>()(
                      (JSContext*)(nullptr),
                      std::declval<JS::Handle<JS::Value>>(),
                      std::declval<ErrorResult&>(), std::declval<Args>()...))>;

 template <typename Callback, typename... Args>
 using ThenResult =
     std::enable_if_t<IsHandlerCallback<Callback, Args...>::value,
                      Result<RefPtr<Promise>, nsresult>>;

 // Similar to the JavaScript then() function. Accepts two lambda function
 // arguments, which it attaches as native resolve/reject handlers, and
 // returns a new promise which:
 // 1. if the ErrorResult contains an error value, rejects with it.
 // 2. else, resolves with a return value.
 //
 // Any additional arguments passed after the callback functions are stored and
 // passed as additional arguments to the functions when it is called. These
 // values will participate in cycle collection for the promise handler, and
 // therefore may safely form reference cycles with the promise chain.
 //
 // Any strong references required by the callbacks should be passed in this
 // manner, rather than using lambda capture, lambda captures do not support
 // cycle collection, and can easily lead to leaks.
 template <typename ResolveCallback, typename RejectCallback, typename... Args>
 ThenResult<ResolveCallback, Args...> ThenCatchWithCycleCollectedArgs(
     ResolveCallback&& aOnResolve, RejectCallback&& aOnReject,
     Args&&... aArgs);

 // Same as ThenCatchWithCycleCollectedArgs, except the rejection error will
 // simply be propagated.
 template <typename Callback, typename... Args>
 ThenResult<Callback, Args...> ThenWithCycleCollectedArgs(
     Callback&& aOnResolve, Args&&... aArgs);

 // Same as ThenCatchWithCycleCollectedArgs, except the resolved value will
 // simply be propagated.
 template <typename Callback, typename... Args>
 ThenResult<Callback, Args...> CatchWithCycleCollectedArgs(
     Callback&& aOnReject, Args&&... aArgs);

 // Same as Then[Catch]CycleCollectedArgs but the arguments are gathered into
 // an `std::tuple` and there is an additional `std::tuple` for JS arguments
 // after that.
 template <typename ResolveCallback, typename RejectCallback,
           typename ArgsTuple, typename JSArgsTuple>
 Result<RefPtr<Promise>, nsresult> ThenCatchWithCycleCollectedArgsJS(
     ResolveCallback&& aOnResolve, RejectCallback&& aOnReject,
     ArgsTuple&& aArgs, JSArgsTuple&& aJSArgs);
 template <typename Callback, typename ArgsTuple, typename JSArgsTuple>
 Result<RefPtr<Promise>, nsresult> ThenWithCycleCollectedArgsJS(
     Callback&& aOnResolve, ArgsTuple&& aArgs, JSArgsTuple&& aJSArgs);

 Result<RefPtr<Promise>, nsresult> ThenWithoutCycleCollection(
     const std::function<already_AddRefed<Promise>(
         JSContext*, JS::Handle<JS::Value>, ErrorResult& aRv)>& aCallback);

 // Similar to ThenCatchWithCycleCollectedArgs but doesn't care with return
 // values of the callbacks and does not return a new promise.
 template <typename ResolveCallback, typename RejectCallback, typename... Args>
 void AddCallbacksWithCycleCollectedArgs(ResolveCallback&& aOnResolve,
                                         RejectCallback&& aOnReject,
                                         Args&&... aArgs);

 // This can be null if this promise is made after the corresponding JSContext
 // is dead.
 JSObject* PromiseObj() const { return mPromiseObj; }

 void AppendNativeHandler(PromiseNativeHandler* aRunnable);

 nsIGlobalObject* GetGlobalObject() const { return mGlobal; }

 // Create a dom::Promise from a given SpiderMonkey Promise object.
 // aPromiseObj MUST be in the compartment of aGlobal's global JS object.
 // Pass ePropagateUserInteraction for aPropagateUserInteraction if you want
 // the promise resolve handler to be called as if we were handling user
 // input events in case we are currently handling user input events.
 static already_AddRefed<Promise> CreateFromExisting(
     nsIGlobalObject* aGlobal, JS::Handle<JSObject*> aPromiseObj,
     PropagateUserInteraction aPropagateUserInteraction =
         eDontPropagateUserInteraction);

 enum class PromiseState { Pending, Resolved, Rejected };

 PromiseState State() const;

 static already_AddRefed<Promise> CreateResolvedWithUndefined(
     nsIGlobalObject* aGlobal, ErrorResult& aRv);

 static already_AddRefed<Promise> CreateRejected(
     nsIGlobalObject* aGlobal, JS::Handle<JS::Value> aRejectionError,
     ErrorResult& aRv);

 static already_AddRefed<Promise> CreateRejectedWithTypeError(
     nsIGlobalObject* aGlobal, const nsACString& aMessage, ErrorResult& aRv);

 // The rejection error will be consumed if the promise is successfully
 // created, else the error will remain and rv.Failed() will keep being true.
 // This intentionally is not an overload of CreateRejected to prevent
 // accidental omission of the second argument. (See also bug 1762233 about
 // removing its third argument.)
 static already_AddRefed<Promise> CreateRejectedWithErrorResult(
     nsIGlobalObject* aGlobal, ErrorResult& aRejectionError);

 // Converts an integer or DOMException to nsresult, or otherwise returns
 // NS_ERROR_DOM_NOT_NUMBER_ERR (which is exclusive for this function).
 // Can be used to convert JS::Value passed to rejection handler so that native
 // error handlers e.g. MozPromise can consume it.
 static nsresult TryExtractNSResultFromRejectionValue(
     JS::Handle<JS::Value> aValue);

protected:
 template <typename ResolveCallback, typename RejectCallback, typename... Args,
           typename... JSArgs>
 Result<RefPtr<Promise>, nsresult> ThenCatchWithCycleCollectedArgsJSImpl(
     Maybe<ResolveCallback>&& aOnResolve, Maybe<RejectCallback>&& aOnReject,
     std::tuple<Args...>&& aArgs, std::tuple<JSArgs...>&& aJSArgs);
 template <typename ResolveCallback, typename RejectCallback, typename... Args>
 ThenResult<ResolveCallback, Args...> ThenCatchWithCycleCollectedArgsImpl(
     Maybe<ResolveCallback>&& aOnResolve, Maybe<RejectCallback>&& aOnReject,
     Args&&... aArgs);

 // Legacy method for throwing DOMExceptions.  Only used by media code at this
 // point, via DetailedPromise.  Do NOT add new uses!  When this is removed,
 // remove the friend declaration in ErrorResult.h.
 inline void MaybeRejectWithDOMException(nsresult rv,
                                         const nsACString& aMessage) {
   ErrorResult res;
   res.ThrowDOMException(rv, aMessage);
   MaybeReject(std::move(res));
 }

 struct PromiseCapability;

 // Do NOT call this unless you're Promise::Create or
 // Promise::CreateFromExisting.  I wish we could enforce that from inside this
 // class too, somehow.
 explicit Promise(nsIGlobalObject* aGlobal);

 virtual ~Promise();

 // Do JS-wrapping after Promise creation.
 // Pass ePropagateUserInteraction for aPropagateUserInteraction if you want
 // the promise resolve handler to be called as if we were handling user
 // input events in case we are currently handling user input events.
 // The error code can be:
 // * NS_ERROR_UNEXPECTED when AutoJSAPI.Init fails
 // * NS_ERROR_OUT_OF_MEMORY when NewPromiseObject throws OOM
 // * NS_ERROR_NOT_INITIALIZED when NewPromiseObject fails without OOM
 void CreateWrapper(ErrorResult& aRv,
                    PropagateUserInteraction aPropagateUserInteraction =
                        eDontPropagateUserInteraction);

private:
 void MaybeResolve(JSContext* aCx, JS::Handle<JS::Value> aValue);
 void MaybeReject(JSContext* aCx, JS::Handle<JS::Value> aValue);

 template <typename T>
 void MaybeSomething(T&& aArgument, MaybeFunc aFunc) {
   if (NS_WARN_IF(!PromiseObj())) {
     return;
   }

   AutoAllowLegacyScriptExecution exemption;
   AutoEntryScript aes(mGlobal, "Promise resolution or rejection");
   JSContext* cx = aes.cx();

   JS::Rooted<JS::Value> val(cx);
   if (!ToJSValue(cx, std::forward<T>(aArgument), &val)) {
     HandleException(cx);
     return;
   }

   (this->*aFunc)(cx, val);
 }

 void HandleException(JSContext* aCx);

 bool MaybePropagateUserInputEventHandling();

 RefPtr<nsIGlobalObject> mGlobal;

 JS::Heap<JSObject*> mPromiseObj;
};

}  // namespace mozilla::dom

extern "C" {
// These functions are used in the implementation of ffi bindings for
// dom::Promise from Rust in xpcom crate.
void DomPromise_AddRef(mozilla::dom::Promise* aPromise);
void DomPromise_Release(mozilla::dom::Promise* aPromise);
void DomPromise_RejectWithVariant(mozilla::dom::Promise* aPromise,
                                 nsIVariant* aVariant);
void DomPromise_ResolveWithVariant(mozilla::dom::Promise* aPromise,
                                  nsIVariant* aVariant);
}

#endif  // mozilla_dom_Promise_h