components/js_injection/common/interfaces.mojom

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

module js_injection.mojom;

import "components/origin_matcher/origin_matcher.mojom";
import "mojo/public/mojom/base/big_buffer.mojom";
import "mojo/public/mojom/base/string16.mojom";
import "third_party/blink/public/mojom/messaging/message_port_descriptor.mojom";

// JsObject struct represents a JavaScript object we will inject in the main
// JavaScript world of a frame. |js_object_name| will be used as the name of the
// JavaScript object. We will inject the object if the frame's origin matches
// |origin_matcher|. |js_to_browser_messaging| will be used for that JavaScript
// object to send message back to browser side. |browser_to_js_factory| is used
// when the kLazyBindJsInjection feature is enabled to request a
// BrowserToJsMessaging pipe from the renderer when needed. If this is not set,
// SetBrowserToJsMessaging() must be called from the renderer to pass the pipe.
struct JsObject {
  mojo_base.mojom.String16 js_object_name;
  pending_associated_remote<JsToBrowserMessaging> js_to_browser_messaging;
  pending_associated_receiver<BrowserToJsMessagingFactory>
      browser_to_js_factory;
  origin_matcher.mojom.OriginMatcher origin_matcher;
};

// DocumentStartJavaScript struct contains the JavaScript snippet |script| and
// the corresponding |origin_matcher|. We will run the script if the frame's
// origin matches any rules in the |origin_matcher|.
struct DocumentStartJavaScript {
  int32 script_id;
  mojo_base.mojom.String16 script;
  origin_matcher.mojom.OriginMatcher origin_matcher;
};

// The ArrayBuffer arm of the JsWebMessage union below, which contains the
// ArrayBuffer payload sent between JavaScript and browser.
struct JsWebMessageArrayBufferValue {
  mojo_base.mojom.BigBuffer array_buffer_value;
  // If is_resizable_by_user_javascript is false, then max_byte_length is
  // unused.
  //
  // TODO(crbug.com/40489779): Use a wrapped uint64 or uint64? once supported.
  bool is_resizable_by_user_javascript = false;
  uint64 max_byte_length = 0;
};

// JsWebMessage struct contains the message payload sent between
// JavaScript and Browser.
union JsWebMessage {
  mojo_base.mojom.String16 string_value;
  JsWebMessageArrayBufferValue array_buffer_value;
};

// For JavaScript postMessage() API, implemented by browser.
interface JsToBrowserMessaging {
  // Called from renderer, browser receives |message| and possible |ports|,
  // The |message| is an opaque type and the contents are defined by the client
  // of this API.
  PostMessage(JsWebMessage message,
              array<blink.mojom.MessagePortDescriptor> ports);

  // When there is a new BrowserToJsMessaging created in renderer, we need to
  // send/ it to browser, so browser could send message back to Js.
  SetBrowserToJsMessaging(
    pending_associated_remote<BrowserToJsMessaging> browser_to_js_messaging);
};

// Client interface to send batch messages related to JsObject.
interface JsObjectsClient {
  // Notifies the browser that the window object has been cleared for the frame.
  OnWindowObjectCleared();
};

// Allows lazily binding the BrowserToJsMessaging pipe.
interface BrowserToJsMessagingFactory {
  // Sends a new BrowsertoJsMessaging pipe to the renderer.
  SendBrowserToJsMessaging(
    pending_associated_receiver<BrowserToJsMessaging> browser_to_js_messaging);
};

// For the browser to reply back to injected JavaScript object. Implemented by
// the renderer.
interface BrowserToJsMessaging {
  // Called from browser, to send message to page.
  OnPostMessage(JsWebMessage message);
};

// For browser to configure renderer, implemented by renderer.
interface JsCommunication {
  // Called from browser, to tell renderer that if we need to inject
  // JavaScript objects to the frame based on the |js_objects| array.
  SetJsObjects(array<js_injection.mojom.JsObject> js_objects,
               pending_associated_remote<JsObjectsClient> client);

  // Called from browser, to add a script for a frame to run at document start
  // stage. The script will run only if the frame's origin matches any of the
  // allowed_origin_rules.
  AddDocumentStartScript(js_injection.mojom.DocumentStartJavaScript script);

  // Called from browser, to remove the script by the given script_id.
  RemoveDocumentStartScript(int32 script_id);
};