firefox/dom/streams/UnderlyingSourceCallbackHelpers.h

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim:set ts=2 sw=2 sts=2 et cindent: */
/* 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_UnderlyingSourceCallbackHelpers_h
#define mozilla_dom_UnderlyingSourceCallbackHelpers_h

#include "mozilla/DOMEventTargetHelper.h"
#include "mozilla/HoldDropJSObjects.h"
#include "mozilla/dom/Promise.h"
#include "mozilla/dom/UnderlyingSourceBinding.h"
#include "mozilla/WeakPtr.h"
#include "nsIAsyncInputStream.h"
#include "nsISupports.h"
#include "nsISupportsImpl.h"

/* Since the streams specification has native descriptions of some callbacks
 * (i.e. described in prose, rather than provided by user code), we need to be
 * able to pass around native callbacks. To handle this, we define polymorphic
 * classes That cover the difference between native callback and user-provided.
 *
 * The Streams specification wants us to invoke these callbacks, run through
 * WebIDL as if they were methods. So we have to preserve the underlying object
 * to use as the This value on invocation.
 */
enum class nsresult : uint32_t;

namespace mozilla::dom {

class StrongWorkerRef;
class BodyStreamHolder;
class ReadableStreamControllerBase;
class ReadableStream;

class UnderlyingSourceAlgorithmsBase : public nsISupports {
 public:
  NS_DECL_CYCLE_COLLECTING_ISUPPORTS
  NS_DECL_CYCLE_COLLECTION_CLASS(UnderlyingSourceAlgorithmsBase)

  MOZ_CAN_RUN_SCRIPT virtual void StartCallback(
      JSContext* aCx, ReadableStreamControllerBase& aController,
      JS::MutableHandle<JS::Value> aRetVal, ErrorResult& aRv) = 0;

  // A promise-returning algorithm that pulls data from the underlying byte
  // source
  MOZ_CAN_RUN_SCRIPT virtual already_AddRefed<Promise> PullCallback(
      JSContext* aCx, ReadableStreamControllerBase& aController,
      ErrorResult& aRv) = 0;

  // A promise-returning algorithm, taking one argument (the cancel reason),
  // which communicates a requested cancelation to the underlying byte source
  MOZ_CAN_RUN_SCRIPT virtual already_AddRefed<Promise> CancelCallback(
      JSContext* aCx, const Optional<JS::Handle<JS::Value>>& aReason,
      ErrorResult& aRv) = 0;

  // Implement this when you need to release underlying resources immediately
  // from closed(canceled)/errored streams, without waiting for GC.
  virtual void ReleaseObjects() {}

  // Can be used to read chunks directly via nsIInputStream to skip JS-related
  // overhead, if this readable stream is a wrapper of a native stream.
  // Currently used by Fetch helper functions e.g. new Response(stream).text()
  virtual nsIInputStream* MaybeGetInputStreamIfUnread() { return nullptr; }

  // https://streams.spec.whatwg.org/#other-specs-rs-create
  // By "native" we mean "instances initialized via the above set up or set up
  // with byte reading support algorithms (not, e.g., on web-developer-created
  // instances)"
  virtual bool IsNative() { return true; }

 protected:
  virtual ~UnderlyingSourceAlgorithmsBase() = default;
};

class UnderlyingSourceAlgorithms final : public UnderlyingSourceAlgorithmsBase {
 public:
  NS_DECL_ISUPPORTS_INHERITED
  NS_DECL_CYCLE_COLLECTION_SCRIPT_HOLDER_CLASS_INHERITED(
      UnderlyingSourceAlgorithms, UnderlyingSourceAlgorithmsBase)

  UnderlyingSourceAlgorithms(nsIGlobalObject* aGlobal,
                             JS::Handle<JSObject*> aUnderlyingSource,
                             UnderlyingSource& aUnderlyingSourceDict)
      : mGlobal(aGlobal), mUnderlyingSource(aUnderlyingSource) {
    // Step 6. (implicit Step 2.)
    if (aUnderlyingSourceDict.mStart.WasPassed()) {
      mStartCallback = aUnderlyingSourceDict.mStart.Value();
    }

    // Step 7. (implicit Step 3.)
    if (aUnderlyingSourceDict.mPull.WasPassed()) {
      mPullCallback = aUnderlyingSourceDict.mPull.Value();
    }

    // Step 8. (implicit Step 4.)
    if (aUnderlyingSourceDict.mCancel.WasPassed()) {
      mCancelCallback = aUnderlyingSourceDict.mCancel.Value();
    }

    mozilla::HoldJSObjects(this);
  };

  MOZ_CAN_RUN_SCRIPT void StartCallback(
      JSContext* aCx, ReadableStreamControllerBase& aController,
      JS::MutableHandle<JS::Value> aRetVal, ErrorResult& aRv) override;

  MOZ_CAN_RUN_SCRIPT already_AddRefed<Promise> PullCallback(
      JSContext* aCx, ReadableStreamControllerBase& aController,
      ErrorResult& aRv) override;

  MOZ_CAN_RUN_SCRIPT already_AddRefed<Promise> CancelCallback(
      JSContext* aCx, const Optional<JS::Handle<JS::Value>>& aReason,
      ErrorResult& aRv) override;

  bool IsNative() override { return false; }

 protected:
  ~UnderlyingSourceAlgorithms() override { mozilla::DropJSObjects(this); };

 private:
  // Virtually const, but are cycle collected
  nsCOMPtr<nsIGlobalObject> mGlobal;
  JS::Heap<JSObject*> mUnderlyingSource;
  MOZ_KNOWN_LIVE RefPtr<UnderlyingSourceStartCallback> mStartCallback;
  MOZ_KNOWN_LIVE RefPtr<UnderlyingSourcePullCallback> mPullCallback;
  MOZ_KNOWN_LIVE RefPtr<UnderlyingSourceCancelCallback> mCancelCallback;
};

// https://streams.spec.whatwg.org/#readablestream-set-up
// https://streams.spec.whatwg.org/#readablestream-set-up-with-byte-reading-support
// Wrappers defined by the "Set up" methods in the spec. This helps you just
// return nullptr when an error occurred as this wrapper converts it to a
// rejected promise.
// Note that StartCallback is only for JS consumers to access
// the controller, and thus is no-op here since native consumers can call
// `EnqueueNative()` etc. without direct controller access.
class UnderlyingSourceAlgorithmsWrapper
    : public UnderlyingSourceAlgorithmsBase {
  void StartCallback(JSContext*, ReadableStreamControllerBase&,
                     JS::MutableHandle<JS::Value> aRetVal, ErrorResult&) final;

  MOZ_CAN_RUN_SCRIPT already_AddRefed<Promise> PullCallback(
      JSContext* aCx, ReadableStreamControllerBase& aController,
      ErrorResult& aRv) final;

  MOZ_CAN_RUN_SCRIPT already_AddRefed<Promise> CancelCallback(
      JSContext* aCx, const Optional<JS::Handle<JS::Value>>& aReason,
      ErrorResult& aRv) final;

  MOZ_CAN_RUN_SCRIPT virtual already_AddRefed<Promise> PullCallbackImpl(
      JSContext* aCx, ReadableStreamControllerBase& aController,
      ErrorResult& aRv) {
    // pullAlgorithm is optional, return null by default
    return nullptr;
  }

  MOZ_CAN_RUN_SCRIPT virtual already_AddRefed<Promise> CancelCallbackImpl(
      JSContext* aCx, const Optional<JS::Handle<JS::Value>>& aReason,
      ErrorResult& aRv) {
    // cancelAlgorithm is optional, return null by default
    return nullptr;
  }
};

class InputToReadableStreamAlgorithms;

// This class exists to isolate InputToReadableStreamAlgorithms from the
// nsIAsyncInputStream.  If we call AsyncWait(this,...), it holds a
// reference to 'this' which can't be cc'd, and we can leak the stream,
// causing a Worker to assert with globalScopeAlive.  By isolating
// ourselves from the inputstream, we can safely be CC'd if needed and
// will inform the inputstream to shut down.
class InputStreamHolder final : public nsIInputStreamCallback,
                                public GlobalTeardownObserver {
 public:
  NS_DECL_THREADSAFE_ISUPPORTS
  NS_DECL_NSIINPUTSTREAMCALLBACK

  InputStreamHolder(nsIGlobalObject* aGlobal,
                    InputToReadableStreamAlgorithms* aCallback,
                    nsIAsyncInputStream* aInput);

  void Init(JSContext* aCx);

  void DisconnectFromOwner() override;

  // Used by global teardown
  void Shutdown();

  // These just proxy the calls to the nsIAsyncInputStream
  nsresult AsyncWait(uint32_t aFlags, uint32_t aRequestedCount,
                     nsIEventTarget* aEventTarget);
  nsresult Available(uint64_t* aSize) { return mInput->Available(aSize); }
  nsresult Read(char* aBuffer, uint32_t aLength, uint32_t* aWritten) {
    return mInput->Read(aBuffer, aLength, aWritten);
  }
  nsresult CloseWithStatus(nsresult aStatus) {
    return mInput->CloseWithStatus(aStatus);
  }

  nsIAsyncInputStream* GetInputStream() { return mInput; }

 private:
  ~InputStreamHolder();

  // WeakPtr to avoid cycles
  WeakPtr<InputToReadableStreamAlgorithms> mCallback;
  // To ensure the worker sticks around
  RefPtr<StrongWorkerRef> mAsyncWaitWorkerRef;
  RefPtr<StrongWorkerRef> mWorkerRef;
  nsCOMPtr<nsIAsyncInputStream> mInput;

  // To ensure the underlying source sticks around during an ongoing read
  // operation. mAlgorithms is not cycle collected on purpose, and this holder
  // is responsible to keep the underlying source algorithms until
  // nsIAsyncInputStream responds.
  //
  // This is done because otherwise the whole stream objects may be cycle
  // collected, including the promises created from read(), as our JS engine may
  // throw unsettled promises away for optimization. See bug 1849860.
  RefPtr<InputToReadableStreamAlgorithms> mAsyncWaitAlgorithms;
};

// Using this class means you are also passing the lifetime control of your
// nsIAsyncInputStream, as it will be closed when this class tears down.
class InputToReadableStreamAlgorithms final
    : public UnderlyingSourceAlgorithmsWrapper,
      public nsIInputStreamCallback,
      public SupportsWeakPtr {
  NS_DECL_ISUPPORTS_INHERITED
  NS_DECL_NSIINPUTSTREAMCALLBACK
  NS_DECL_CYCLE_COLLECTION_CLASS_INHERITED(InputToReadableStreamAlgorithms,
                                           UnderlyingSourceAlgorithmsWrapper)

  InputToReadableStreamAlgorithms(JSContext* aCx, nsIAsyncInputStream* aInput,
                                  ReadableStream* aStream);

  // Streams algorithms

  already_AddRefed<Promise> PullCallbackImpl(
      JSContext* aCx, ReadableStreamControllerBase& aController,
      ErrorResult& aRv) override;

  void ReleaseObjects() override;

  nsIInputStream* MaybeGetInputStreamIfUnread() override;

 private:
  ~InputToReadableStreamAlgorithms() {
    if (mInput) {
      mInput->Shutdown();
    }
  }

  MOZ_CAN_RUN_SCRIPT_BOUNDARY void CloseAndReleaseObjects(
      JSContext* aCx, ReadableStream* aStream);

  void WriteIntoReadRequestBuffer(JSContext* aCx, ReadableStream* aStream,
                                  JS::Handle<JSObject*> aBuffer,
                                  uint32_t aLength, uint32_t* aByteWritten,
                                  ErrorResult& aRv);

  // https://streams.spec.whatwg.org/#readablestream-pull-from-bytes
  // (Uses InputStreamHolder for the "byte sequence" in the spec)
  MOZ_CAN_RUN_SCRIPT void PullFromInputStream(JSContext* aCx,
                                              uint64_t aAvailable,
                                              ErrorResult& aRv);

  void ErrorPropagation(JSContext* aCx, ReadableStream* aStream,
                        nsresult aError);

  // Common methods

  bool IsClosed() { return !mInput; }

  nsCOMPtr<nsIEventTarget> mOwningEventTarget;

  // This promise is created by PullCallback and resolved when
  // OnInputStreamReady succeeds. No need to try hard to settle it though, see
  // also ReleaseObjects() for the reason.
  RefPtr<Promise> mPullPromise;

  RefPtr<InputStreamHolder> mInput;

  // mStream never changes after construction and before CC
  MOZ_KNOWN_LIVE RefPtr<ReadableStream> mStream;
};

class NonAsyncInputToReadableStreamAlgorithms
    : public UnderlyingSourceAlgorithmsWrapper {
 public:
  NS_DECL_ISUPPORTS_INHERITED
  NS_DECL_CYCLE_COLLECTION_CLASS_INHERITED(
      NonAsyncInputToReadableStreamAlgorithms,
      UnderlyingSourceAlgorithmsWrapper)

  explicit NonAsyncInputToReadableStreamAlgorithms(nsIInputStream& aInput)
      : mInput(&aInput) {}

  already_AddRefed<Promise> PullCallbackImpl(
      JSContext* aCx, ReadableStreamControllerBase& aController,
      ErrorResult& aRv) override;

  void ReleaseObjects() override {
    if (RefPtr<InputToReadableStreamAlgorithms> algorithms =
            mAsyncAlgorithms.forget()) {
      algorithms->ReleaseObjects();
    }
    if (nsCOMPtr<nsIInputStream> input = mInput.forget()) {
      input->Close();
    }
  }

  nsIInputStream* MaybeGetInputStreamIfUnread() override {
    MOZ_ASSERT(mInput, "Should be only called on non-disturbed streams");
    return mInput;
  }

 private:
  ~NonAsyncInputToReadableStreamAlgorithms() = default;

  nsCOMPtr<nsIInputStream> mInput;
  RefPtr<InputToReadableStreamAlgorithms> mAsyncAlgorithms;
};

}  // namespace mozilla::dom

#endif