extensions/renderer/api/messaging/one_time_message_handler.h

// Copyright 2017 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef EXTENSIONS_RENDERER_API_MESSAGING_ONE_TIME_MESSAGE_HANDLER_H_
#define EXTENSIONS_RENDERER_API_MESSAGING_ONE_TIME_MESSAGE_HANDLER_H_

#include <stdint.h>

#include <memory>
#include <optional>
#include <string>

#include "base/memory/raw_ptr.h"
#include "base/memory/weak_ptr.h"
#include "base/unguessable_token.h"
#include "extensions/common/mojom/message_port.mojom.h"
#include "extensions/renderer/bindings/api_binding_types.h"
#include "extensions/renderer/bindings/get_per_context_data.h"
#include "v8/include/v8-forward.h"

namespace gin {
class Arguments;
}

namespace extensions {

namespace mojom {
enum class ChannelType;
}

class NativeExtensionBindingsSystem;
class ScriptContext;
struct Message;
struct MessageTarget;
struct PortId;

// A class for handling one-time message communication, including
// runtime.sendMessage and extension.sendRequest. These methods use the same
// underlying architecture as long-lived port-based communications (like
// runtime.connect), but are exposed through a simpler API.
// A basic flow will be from an "opener" (the original sender) and a "receiver"
// (the event listener), which will be in two separate contexts (and potentially
// renderer processes). The flow is outlined below:
//
// chrome.runtime.sendMessage(  // initiates the sendMessage flow, triggering
//                              // SendMessage().
//     {foo: bar},              // The data sent with SendMessage().
//     function() { ... });     // The response callback in SendMessage().
//
// This creates a new opener port in the context, and posts a message to it
// with the data. The browser then dispatches this to other renderers.
//
// In another context, we have:
// chrome.runtime.onMessage.addListener(function(message, sender, reply) {
//   ...
//   reply(...);
// });
//
// When the renderer receives the connection message, we will create a
// new receiver port in this context via AddReceiver().
// When the message comes in, we reply with DeliverMessage() to the receiver's
// port ID.
// If the receiver replies via the reply callback, it will send a new message
// back along the port to the browser. The browser then sends this message back
// to the opener's renderer, where it is delivered via DeliverMessage().
//
// This concludes the one-time message flow.
class OneTimeMessageHandler {
 public:
  // A unique identifier for a message response callback
  // (`OneTimeMessageCallback`).
  using CallbackID = base::UnguessableToken;

  explicit OneTimeMessageHandler(
      NativeExtensionBindingsSystem* bindings_system);

  OneTimeMessageHandler(const OneTimeMessageHandler&) = delete;
  OneTimeMessageHandler& operator=(const OneTimeMessageHandler&) = delete;

  ~OneTimeMessageHandler();

  // Returns true if the given context has a port with the specified id.
  bool HasPort(ScriptContext* script_context, const PortId& port_id);

  // Initiates a flow to send a message from the given `script_context`. Returns
  // the associated promise if this is a promise based request, otherwise
  // returns an empty promise.
  v8::Local<v8::Promise> SendMessage(
      ScriptContext* script_context,
      const PortId& new_port_id,
      const MessageTarget& target_id,
      mojom::ChannelType channel_type,
      const Message& message,
      binding::AsyncResponseType async_type,
      v8::Local<v8::Function> response_callback,
      mojom::MessagePortHost* message_port_host,
      mojo::PendingAssociatedRemote<mojom::MessagePort> message_port,
      mojo::PendingAssociatedReceiver<mojom::MessagePortHost>
          message_port_host_receiver);

  // Adds a receiving port port to the given `script_context` in preparation
  // for receiving a message to post to the onMessage event.
  void AddReceiver(ScriptContext* script_context,
                   const PortId& target_port_id,
                   v8::Local<v8::Object> sender,
                   const std::string& event_name);

  void AddReceiverForTesting(
      ScriptContext* script_context,
      const PortId& target_port_id,
      v8::Local<v8::Object> sender,
      const std::string& event_name,
      mojo::PendingAssociatedRemote<mojom::MessagePort>& message_port_remote,
      mojo::PendingAssociatedReceiver<mojom::MessagePortHost>&
          message_port_host_receiver);

  // Delivers a message to the port, either the event listener or in response
  // to the sender, if one exists with the specified `target_port_id`. Returns
  // true if a message was delivered (i.e., an open channel existed), and false
  // otherwise.
  bool DeliverMessage(ScriptContext* script_context,
                      const Message& message,
                      const PortId& target_port_id);

  // Disconnects the port in the context, if one exists with the specified
  // `target_port_id`. Returns true if a port was disconnected (i.e., an open
  // channel existed), and false otherwise.
  bool Disconnect(ScriptContext* script_context,
                  const PortId& port_id,
                  const std::string& error_message);

  // Gets the number of pending callbacks on the associated per context data for
  // testing purposes.
  int GetPendingCallbackCountForTest(ScriptContext* script_context);

 private:
  // Helper methods to deliver a message to an opener/receiver.
  bool DeliverMessageToReceiver(ScriptContext* script_context,
                                const Message& message,
                                const PortId& target_port_id);
  bool DeliverReplyToOpener(ScriptContext* script_context,
                            const Message& message,
                            const PortId& target_port_id);

  // Helper methods to disconnect an opener/receiver.
  bool DisconnectReceiver(ScriptContext* script_context, const PortId& port_id);
  bool DisconnectOpener(ScriptContext* script_context,
                        const PortId& port_id,
                        const std::string& error_message);

  // Triggered when a receiver responds to a message.
  void OnOneTimeMessageResponse(const PortId& port_id,
                                gin::Arguments* arguments);

  // Creates a JS function that calls `PromiseRejectedResponse()` to handle when
  // listeners return promises that reject.
  v8::Local<v8::Function> CreatePromiseRejectedFunction(
      v8::Isolate* isolate,
      v8::Local<v8::Context> context,
      const PortId& port_id);

  // Triggered when a receiver's returned promise rejects.
  void PromiseRejectedResponse(const PortId& port_id,
                               gin::Arguments* arguments);

  using OneTimeMessageCallback =
      base::OnceCallback<void(gin::Arguments* arguments)>;

  // Helper method for creating delayed callbacks that can be called as a result
  // of message listener behavior.
  // `cleanup_on_collection` true means that, if `context` is still valid when
  // the v8::Function that is created to call `callback` is garbage collected by
  // v8, we'll remove `callback` from
  // `GetPerContextData<OneTimeMessageContextData>::pending_callbacks` and close
  // the message port.
  v8::Local<v8::Function> CreateDelayedOneTimeMessageCallback(
      v8::Isolate* isolate,
      v8::Local<v8::Context> context,
      const PortId& port_id,
      std::unique_ptr<OneTimeMessageCallback> callback,
      ScriptContext* script_context,
      bool close_port_on_collection);

  // Triggered when the callback for replying is garbage collected. Used to
  // clean up data that was stored for the callback and for closing the
  // associated message port. `callback_id` is the ID of the associated
  // OneTimeMessageCallback, needed for finding and erasing it from the
  // OneTimeMessageContextData.
  void OnDelayedOneTimeMessageCallbackCollected(ScriptContext* script_context,
                                                const PortId& port_id,
                                                CallbackID callback_id);

  // Called when the messaging event has been dispatched with the result of the
  // listeners.
  void OnEventFired(const PortId& port_id, gin::Arguments* arguments);

  // Returns true if any of the listeners responded with `true` or (if enabled)
  // a Promise, indicating they will respond to the call asynchronously. If a
  // Promise is returned, `promise_resolved_function` is attached to its resolve
  // and a reject function is attached to its reject.
  bool CheckAndHandleAsyncListenerReply(
      v8::Isolate* isolate,
      v8::Local<v8::Context> context,
      v8::Local<v8::Value> result,
      const PortId& port_id,
      v8::Local<v8::Function> promise_resolved_function);

  // The associated bindings system. Outlives this object.
  const raw_ptr<NativeExtensionBindingsSystem> bindings_system_;

  base::WeakPtrFactory<OneTimeMessageHandler> weak_factory_{this};
};

}  // namespace extensions

#endif  // EXTENSIONS_RENDERER_API_MESSAGING_ONE_TIME_MESSAGE_HANDLER_H_