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/js_injection/common/enum.mojom";
import "components/origin_matcher/origin_matcher.mojom";
import "mojo/public/mojom/base/big_buffer.mojom";
import "mojo/public/mojom/base/string16.mojom";
import "mojo/public/mojom/base/values.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.
// |js_world| is the enumerated world id for the JS script context. 0 is the
// main page world. Values correspond to the underlying enumeration as defined
// in DOMWrapperWorld::WorldId enum.
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;
  int32 js_world;
};

// JavaScriptExecutable struct contains the JavaScript snippet |script| and the
// corresponding |origin_matcher| and the |js_world| representation.
// We will run the script in |js_world| if the frame's origin matches any rules
// in the |origin_matcher|.
struct JavaScriptExecutable {
  int32 script_id;
  mojo_base.mojom.String16 script;
  origin_matcher.mojom.OriginMatcher origin_matcher;
  DocumentInjectionTime injection_time;
  // Page world is denoted by 0.
  int32 js_world;
};

// 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 the buffer is resizable via JavaScript, the limit to which it can be
  // resized. If it is not resizable via JavaScript, this is not set.
  uint64? javascript_resize_limit;
};

// 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);

  // Execute JavaScript code in the renderer using the same
  // BrowserToJsMessaging pipe.
  OnExecuteJavaScript(
      mojo_base.mojom.BigString16 javascript,
      bool wants_result) =>
          result<mojo_base.mojom.Value, JavaScriptExecutionError>;
};

// 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 the specified
  // stage in the specified world. The script will run only if the frame's
  // origin matches any of the allowed_origin_rules.
  AddPersistentJavaScript(js_injection.mojom.JavaScriptExecutable script);

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

};