content/common/gin_java_bridge.mojom

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

module content.mojom;

import "mojo/public/mojom/base/values.mojom";

// Descriptive errors raised by the gin java bridge.
enum GinJavaBridgeError {
  kGinJavaBridgeNoError,
  kGinJavaBridgeUnknownObjectId,
  kGinJavaBridgeObjectIsGone,
  kGinJavaBridgeMethodNotFound,
  kGinJavaBridgeAccessToObjectGetClassIsBlocked,
  kGinJavaBridgeJavaExceptionRaised,
  kGinJavaBridgeNonAssignableTypes,
  kGinJavaBridgeRenderFrameDeleted,
};

// Interface for adding objects to a frame in the renderer.
// TODO(crbug.com/40554401): This interface mirrors
// `blink.mojom.RemoteObjectGateway` and should be removed once
// crbug.com/794320 is complete.
interface GinJavaBridge {
  // Sent from browser to renderer to add a Java object with the given name.
  // Object IDs are generated on the browser side.
  AddNamedObject(string name, int32 object_id);

  // Sent from browser to renderer to remove a Java object with the given name.
  RemoveNamedObject(string name);

  // Sets the associated GinJavaBridgeHost object.
  SetHost(pending_remote<GinJavaBridgeHost> host);
};

// Implemented in the process hosting the remote object. Allows methods to be
// synchronously invoked on the object.
// TODO(crbug.com/40554401): This interface mirrors `blink.mojom.RemoteObject`
// but without the serialization changes. This should be merged with that
// definition once crbug.com/794320 is complete.
interface GinJavaBridgeRemoteObject {
  // Sent from renderer to browser to get information about methods of
  // the given object. The query will only succeed if inspection of injected
  // objects is enabled on the browser side.
  [Sync]
  GetMethods() => (array<string> method_names);

  // Sent from renderer to browser to find out, if an object has a method with
  // the given name.
  [Sync]
  HasMethod(string method_name) => (bool result);

  // Sent from renderer to browser to invoke a method. Method arguments
  // are chained into |arguments| list. base::Value::List is used for |result|
  // as a container to work around immutability of base::Value.
  // Empty result list indicates that an error has happened on the Java side
  // (either bridge-induced error or an unhandled Java exception) and an
  // exception must be thrown into JavaScript. |error_code| indicates the cause
  // of the error.
  // Some special value types that are not supported by base::Value are encoded
  // as BinaryValues via GinJavaBridgeValue.
  [Sync]
  InvokeMethod(string method_name, mojo_base.mojom.ListValue arguments) =>
    (GinJavaBridgeError error_code, mojo_base.mojom.ListValue result);
};

// Implemented in the process hosting the remote objects. Allows access to an
// object graph.
// TODO(crbug.com/40554401): This class mirrors `blink.mojom.RemoteObjectHost`
// and should be removed once crbug.com/794320 is complete.
interface GinJavaBridgeHost {
  // Binds |receiver| to an implementation of RemoteObject corresponding to
  // |object_id|.
  GetObject(int32 object_id,
            pending_receiver<GinJavaBridgeRemoteObject> receiver);

  // Sent from renderer to browser in two cases:
  //
  //  1. (Main usage) To inform that the JS wrapper of the object has
  //     been completely dereferenced and garbage-collected.
  //
  //  2. To notify the browser that wrapper creation has failed.  The browser
  //     side assumes optimistically that every time an object is returned from
  //     a method, the corresponding wrapper object will be successfully
  //     created on the renderer side. Sending of this message informs the
  //     browser whether this expectation has failed.
  ObjectWrapperDeleted(int32 object_id);
};