content/common/frame.mojom

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

module content.mojom;

import "cc/mojom/browser_controls_state.mojom";
import "content/common/frame_messages.mojom";
import "content/common/native_types.mojom";
import "content/common/navigation_client.mojom";
import "content/common/web_ui.mojom";
import "content/public/common/window_container_type.mojom";
import "ipc/constants.mojom";
import "mojo/public/mojom/base/file_path.mojom";
import "mojo/public/mojom/base/string16.mojom";
import "mojo/public/mojom/base/time.mojom";
import "mojo/public/mojom/base/unguessable_token.mojom";
import "mojo/public/mojom/base/values.mojom";
import "skia/public/mojom/skcolor.mojom";
import "services/network/public/mojom/content_security_policy.mojom";
import "services/network/public/mojom/url_loader.mojom";
import "services/network/public/mojom/url_loader_factory.mojom";
import "services/network/public/mojom/url_request.mojom";
import "services/network/public/mojom/url_response_head.mojom";
import "services/service_manager/public/mojom/interface_provider.mojom";
import "services/viz/public/mojom/compositing/surface_id.mojom";
import "third_party/blink/public/mojom/blob/blob_url_store.mojom";
import "third_party/blink/public/mojom/browser_interface_broker.mojom";
import "third_party/blink/public/mojom/commit_result/commit_result.mojom";
import "third_party/blink/public/mojom/conversions/conversions.mojom";
import "third_party/blink/public/mojom/devtools/console_message.mojom";
import "third_party/blink/public/mojom/fenced_frame/fenced_frame.mojom";
import "third_party/blink/public/mojom/frame/frame.mojom";
import "third_party/blink/public/mojom/frame/frame_owner_properties.mojom";
import "third_party/blink/public/mojom/frame/frame_policy.mojom";
import "third_party/blink/public/mojom/frame/frame_replication_state.mojom";
import "third_party/blink/public/mojom/frame/lifecycle.mojom";
import "third_party/blink/public/mojom/frame/policy_container.mojom";
import "third_party/blink/public/mojom/frame/tree_scope_type.mojom";
import "third_party/blink/public/mojom/loader/referrer.mojom";
import "third_party/blink/public/mojom/navigation/navigation_policy.mojom";
import "third_party/blink/public/mojom/loader/resource_load_info.mojom";
import "third_party/blink/public/mojom/loader/url_loader_factory_bundle.mojom";
import "third_party/blink/public/mojom/messaging/transferable_message.mojom";
import "third_party/blink/public/mojom/navigation/navigation_params.mojom";
import "third_party/blink/public/mojom/page/page.mojom";
import "third_party/blink/public/mojom/widget/platform_widget.mojom";
import "third_party/blink/public/mojom/page/widget.mojom";
import "third_party/blink/public/mojom/portal/portal.mojom";
import "third_party/blink/public/mojom/renderer_preferences.mojom";
import "third_party/blink/public/mojom/service_worker/controller_service_worker.mojom";
import "third_party/blink/public/mojom/service_worker/service_worker_container.mojom";
import "third_party/blink/public/mojom/tokens/tokens.mojom";
import "third_party/blink/public/mojom/webpreferences/web_preferences.mojom";
import "third_party/blink/public/mojom/widget/visual_properties.mojom";
import "third_party/blink/public/mojom/window_features/window_features.mojom";
import "ui/accessibility/mojom/ax_tree_update.mojom";
import "ui/base/mojom/window_open_disposition.mojom";
import "ui/gfx/geometry/mojom/geometry.mojom";
import "url/mojom/origin.mojom";
import "url/mojom/url.mojom";

[Native]
struct PageState;

// A View (i.e. a "main frame") can be created for a few different cases, these
// values are used to specify which it is.
enum ViewWidgetType {
  // A standard view that's the top-level widget in a frame hierarchy.
  kTopLevel,
  // A GuestView used to render contents inside a <webview> element.
  kGuestView,
  // A view used to render contents inside a <portal> element.
  kPortal,
  // A view used to render contents inside a <fencedframe> element.
  kFencedFrame
};

// The type of the frame owner element for a child frame. In cross-process
// frames, this would be the type of the HTMLFrameOwnerElement for the remote
// child frame in the parent process. Note that only HTMLFrameOwnerElements for
// which CreateChildFrame is used are included here. Other
// HTMLFrameOwnerElements such as portals do not use this.
enum ChildFrameOwnerElementType {
  kIframe,
  kObject,
  kEmbed,
  kFrame,
  // Note that only Fenced Frames based on Shadow DOM may create child frames.
  // See crbug.com/1123606.
  kFencedframe
};

struct CreateViewParams {
  // Renderer-wide preferences.
  blink.mojom.RendererPreferences renderer_preferences;

  // Preferences for this view.
  blink.mojom.WebPreferences web_preferences;

  // The ID of the view to be created.
  int32 view_id = IPC.mojom.kRoutingIdNone;

  // The session storage namespace ID this view should use.
  string session_storage_namespace_id;

  // The frame token of the opener frame if one exists, or absl::nullopt
  // otherwise.
  blink.mojom.FrameToken? opener_frame_token;

  // Information that needs to be replicated to the view's main frame, e.g.
  // frame name and sandbox flags.
  blink.mojom.FrameReplicationState replication_state;

  // Used for devtools instrumentation and trace-ability. The token is shared
  // across all frames (local or remotes) representing the same logical frame
  // tree node, and is used by Blink and content to tag calls and requests for
  // instrumentation purposes, allowing them to be attributed to a context
  // frame.
  //
  // Must not be used to look up a RenderFrameHostImpl or RenderFrameProxyHost
  // in the browser process, as the token is shared, making the mapping
  // ambiguous and non-authoritative.
  mojo_base.mojom.UnguessableToken devtools_main_frame_token;

  CreateMainFrameUnion main_frame;

  // Whether the RenderView should initially be hidden.
  bool hidden;

  // Prerender2: Whether the RenderView is for a prerendered page.
  bool is_prerendering;

  // When true, all RenderWidgets under this RenderView will never be shown to
  // the user, and thus never composited, and will not need to produce pixels
  // for display. This allows the renderer to optimize and avoid resources used
  // for displaying graphical output.
  bool never_composited;

  // Whether the window associated with this view was created by another window.
  bool window_was_opened_by_another_window;

  // Whether lookup of frames in the created RenderView (e.g. lookup via
  // window.open or via <a target=...>) should be renderer-wide (i.e. going
  // beyond the usual opener-relationship-based BrowsingInstance boundaries).
  bool renderer_wide_named_frame_lookup;

  // Indicates whether the view is a regular top-level widget or some other
  // nested "main frame" widget type.
  ViewWidgetType type;

  // Endpoint for any messages that are broadcast to all views in a WebContents.
  pending_associated_receiver<blink.mojom.PageBroadcast> blink_page_broadcast;

  // Base background color of this view. Only used by a local main frame.
  skia.mojom.SkColor? base_background_color;
};

// A union to distinguish between parameters specific to local main frame
// creation and remote main frame creation.
union CreateMainFrameUnion {
  CreateLocalMainFrameParams local_params;
  CreateRemoteMainFrameParams remote_params;
};

// Parameters used for browser-initiated local main frame creation.
struct CreateLocalMainFrameParams {
  // The frame token. Used to map between LocalFrame and RenderFrameHostImpl.
  blink.mojom.LocalFrameToken token;

  // The ID of the main frame hosted in the view. Must not be kRoutingIdNone.
  int32 routing_id = IPC.mojom.kRoutingIdNone;

  // The communication interfaces for the WebLocalFrame in blink.
  pending_associated_receiver<content.mojom.Frame> frame;

  pending_remote<blink.mojom.BrowserInterfaceBroker> interface_broker;

  // Whether or not the frame has previously committed a real load.
  bool has_committed_real_load;

  // Null when the main frame has no policy container yet (for example, because
  // it is a speculative RenderFrameHost), and the policy container will be
  // sent during CommitNavigation.
  blink.mojom.PolicyContainer? policy_container;

  CreateFrameWidgetParams widget_params;

  // Subresource loader factories to be used by the initial empty document.
  blink.mojom.URLLoaderFactoryBundle subresource_loader_factories;
};

// Parameters used for brower-initiated remote main frame creation.
struct CreateRemoteMainFrameParams {
  blink.mojom.RemoteFrameToken token;

  // The ID of the proxy object for the main frame in this view. Must not be
  // kRoutingIdNone.
  int32 routing_id = IPC.mojom.kRoutingIdNone;

  // The communication channels for the RemoteMainFrame in this view.
  RemoteMainFrameInterfaces main_frame_interfaces;
};

// Parameters used for creating a new frame widget.
struct CreateFrameWidgetParams {
  // Gives the routing ID for the RenderWidget that will be attached to the
  // new RenderFrame.
  int32 routing_id;

  // The communication interfaces for the WebFrameWidget in blink.
  pending_associated_remote<blink.mojom.FrameWidgetHost> frame_widget_host;
  pending_associated_receiver<blink.mojom.FrameWidget> frame_widget;
  pending_associated_remote<blink.mojom.WidgetHost> widget_host;
  pending_associated_receiver<blink.mojom.Widget> widget;

  // The initial visual properties of the widget.
  blink.mojom.VisualProperties visual_properties;
};

// Used for recreating child frames after a crash (does this still happen?) and
// speculative/provisional frames (including main frame).
//
// "Normal" child frame creation (via inserting a new frame owner element into
// the active document) does not use these params and is routed via
// CreateChildFrame().
//
// "Normal" main frame creation (whether browser-initiated, e.g. opening a new
// tab, or renderer-initiated, e.g. window.open()) also do not use these params
// and are routed via CreateView() and CreateNewWindow() respectively.
//
struct CreateFrameParams {
  // The frame token. Used to map between LocalFrame and RenderFrameHostImpl.
  blink.mojom.LocalFrameToken token;

  // Specifies the routing ID of the new RenderFrame object.
  int32 routing_id;

  // If a valid |previous_routing_id| is provided, the new frame will be
  // configured to replace either the previous frame or the previous proxy on
  // commit.
  int32 previous_routing_id;

  // Specifies the new frame's opener.  The opener will be null if this is
  // absl::nullopt.
  blink.mojom.FrameToken? opener_frame_token;

  // The new frame should be created as a child of the object
  // identified by |parent_routing_id| or as top level if that is
  // MSG_ROUTING_NONE.
  int32 parent_routing_id;

  // Identifies the previous sibling of the new frame, so that the new frame is
  // inserted into the correct place in the frame tree.  If this is
  // MSG_ROUTING_NONE, the frame will be created as the leftmost child of its
  // parent frame, in front of any other children.
  int32 previous_sibling_routing_id;

  pending_remote<blink.mojom.BrowserInterfaceBroker> interface_broker;

  blink.mojom.TreeScopeType tree_scope_type;

  // When the new frame has a parent, |replication_state| holds the new frame's
  // properties replicated from the process rendering the parent frame, such as
  // the new frame's sandbox flags.
  blink.mojom.FrameReplicationState replication_state;

  // Used for devtools instrumentation and trace-ability. The token is
  // propagated to Blink's LocalFrame and both Blink and content/
  // can tag calls and requests with this instrumentation token in order to
  // attribute them to the context frame.
  // |devtools_frame_token| is only defined by the browser and is never
  // sent back from the renderer in the control calls.
  mojo_base.mojom.UnguessableToken devtools_frame_token;

  // When the new frame has a parent, |frame_owner_properties| holds the
  // properties of the HTMLFrameOwnerElement from the parent process.
  // Note that unlike FrameReplicationState, this is not replicated for remote
  // frames.
  blink.mojom.FrameOwnerProperties frame_owner_properties;

  // Specifies properties for a new RenderWidget that will be attached to the
  // new RenderFrame (if one is needed).
  CreateFrameWidgetParams? widget_params;

  // Whether or not the frame has previously committed a real load.
  bool has_committed_real_load;

  // The policy container for the frame to be created. This can be null if we
  // could not determine a policy container yet, for example in case of a
  // speculative RenderFrameHost. In that case, the final policy container will
  // be sent along CommitNavigation.
  blink.mojom.PolicyContainer? policy_container;

  // The mojo connection to the mojom::Frame in the renderer.
  pending_associated_receiver<content.mojom.Frame> frame;
};

// Provided with each call to Frame::GetSerializedHtmlWithLocalLinks() so that
// the renderer can notify the browser process each time that a chunk of HTML
// data gets serialized, as well as when the entire process is finished.
interface FrameHTMLSerializerHandler {
  // Sent by the renderer as a response to GetSerializedHtmlWithLocalLinks() to
  // indicate that HTML data has been serialized, included in |data_buffer|.
  DidReceiveData(string data_buffer);

  // Reports that the serialization process is finished. It is expected to
  // receive this message right after the last time DidReceiveData() is called.
  Done();
};

struct SnapshotAccessibilityTreeParams {
  // See ui/accessibility/ax_mode.h for valid values of |ax_mode|.
  uint32 ax_mode;

  // If true, nodes that are entirely offscreen will have their entire
  // subtree excluded.  Note that this heuristic is imperfect, and
  // an absolute-positioned node that's visible, but whose ancestors
  // are entirely offscreen, may get excluded.
  bool exclude_offscreen;

  // The maximum number of nodes to snapshot before exiting early.
  // Note that this is not a hard limit; once this limit is reached a
  // few more nodes may be added in order to ensure a well-formed
  // tree is returned. Use 0 for no max. The corresponding C++ code
  // uses size_t.
  uint64 max_nodes;

  // The maximum amount of time to spend snapshotting the tree. Like
  // max_nodes, this is not a hard limit, and once this limit is reached
  // a few more nodes may be added in order to ensure a well-formed tree.
  // Use 0 for no timeout.
  mojo_base.mojom.TimeDelta timeout;
};

// An enumeration specifying the reason of the frame deletion.
enum FrameDeleteIntention {
  // The frame being deleted isn't a (speculative) main frame.
  kNotMainFrame,
  // The frame being deleted is a speculative main frame, and it is being
  // deleted as part of the shutdown for that WebContents. The entire RenderView
  // etc will be destroyed by a separate IPC sent later.
  kSpeculativeMainFrameForShutdown,
  // The frame being deleted is a speculative main frame, and it is being
  // deleted because the speculative navigation was cancelled. This is not part
  // of shutdown.
  kSpeculativeMainFrameForNavigationCancelled,
};

// Struct for communication channels of the RemoteFrame in blink.
struct RemoteMainFrameInterfaces {
  pending_associated_remote<blink.mojom.RemoteMainFrameHost> main_frame_host;
  pending_associated_receiver<blink.mojom.RemoteMainFrame> main_frame;
};

// Implemented by the frame provider, and must be associated with other content
// mojoms bound to frames, widgets, views, and currently also with the legacy
// IPC channel.
// KEEP THE COMMIT FUNCTIONS IN SYNC in content/common/navigation_client.mojom.
// These will eventually be removed from Frame.
interface Frame {
  // Tells the renderer that a same-document navigation should be committed.
  // The renderer will return a status value indicating whether the commit
  // could proceed as expected or not. In particular, it might be necessary to
  // restart the navigation if it is no-longer same-document, which can happen
  // if the renderer committed another navigation in the meantime.
  CommitSameDocumentNavigation(
      blink.mojom.CommonNavigationParams common_params,
      blink.mojom.CommitNavigationParams request_params)
      => (blink.mojom.CommitResult commit_result);

  // Provides the renderer an updated |subresource_loader_factories|.
  //
  // This method is intended to fix broken loaders after a Network Service
  // crash, and is only used when Network Service is enabled.
  //
  // The new bundle contains replacement factories for a subset of the
  // receiver's existing bundle.
  UpdateSubresourceLoaderFactories(
      blink.mojom.URLLoaderFactoryBundle subresource_loader_factories);

  // Indicates that the frame host (browser) wants the |untrusted_stack_trace|
  // parameter of DidAddMessageToConsole() filled in for Error messages if at
  // all possible.
  SetWantErrorMessageStackTrace();

  // Unload this RenderFrame and replace it by a RenderFrameProxy, so the frame
  // can navigate to a document rendered by a different process. The unload can
  // fail if the RenderFrame is currently detached (it was removed from the
  // frame tree before the Unload was received). If successful this message will
  // send back AgentSchedulingGroupHost::DidUnloadRenderFrame message. This
  // cannot be a standard reply callback because the unload acknowledgement must
  // be posted back to the event loop to be invoked later. This is to ensure
  // that any postMessage() calls executed by JS during unload are dispatched,
  // since postMessage dispatch is always scheduled asynchronously.
  //
  // `new_remote_frame_routing_id`, `new_remote_frame_replication_state`,
  // `new_remote_frame_token`, and `new_remote_main_frame_interfaces` are used
  // to construct the new RenderFrameProxy. `is_loading` mirrors the loading
  // state of the FrameTreeNode's current RenderFrameHost and determines whether
  // the newly-constructed RenderFrameProxy is marked as loading or not.
  Unload(
      int32 new_remote_frame_routing_id,
      bool is_loading,
      blink.mojom.FrameReplicationState new_remote_frame_replication_state,
      blink.mojom.RemoteFrameToken new_remote_frame_token,
      RemoteMainFrameInterfaces new_remote_main_frame_interfaces);

  // Delete the frame. This is only called for child frames that the browser
  // wants to detach, or for speculative main frames which are owned by the
  // browser process. Committed main frames are owned by the renderer's WebView
  // and can not be deleted directly.
  Delete(FrameDeleteIntention intention);

  // Requests that a speculative RenderFrameHost which the browser has already
  // sent a `CommitNavigation()` to should swap itself back out for a
  // RenderFrameProxy to effectively undo the `CommitNavigation()`.
  //
  // This is needed when discarding a speculative RenderFrameHost that's already
  // been asked to commit a navigation, as the state between the browser and
  // renderer would otherwise be out of sync:
  //
  // - from the perspective of the browser process, the speculative
  //   RenderFrameHost has not yet committed as it has not yet acknowledged the
  //   `CommitNavigation()` with `DidCommitNavigation()`.
  // - but any IPCs sent from the browser to the renderer will see that the
  //   provisional RenderFrame has already been swapped in and the
  //   RenderFrameProxy it replaced destroyed.
  //
  // Note: This, of course, does not work for RenderDocument, since the
  // provisional RenderFrame replaces *another* RenderFrame when it commits. The
  // state associated with the replaced RenderFrame is already gone, and it's
  // impossible to restore it. Fixing this issue for RenderDocument will
  // require serious reworking of how navigations are committed.
  //
  // While this is very similar to `Unload()`, the renderer will not send any
  // unload ACK back to the browser on completion. As a result, there is no
  // special handling to ensure messages queued by Window.postMessage() are
  // forwarded.
  //
  // `new_remote_frame_routing_id`, `new_remote_frame_replication_state`,
  // `new_remote_frame_token`, and `new_remote_main_frame_interfaces` are used
  // to construct the new RenderFrameProxy. `is_loading` mirrors the loading
  // state of the FrameTreeNode's current RenderFrameHost and determines whether
  // the newly-constructed RenderFrameProxy is marked as loading or not.
  //
  // TODO(dcheng): It's unclear if `is_loading` is necessary; presently, it
  // always seems to be true when this IPC is called.
  UndoCommitNavigation(
      int32 new_remote_frame_routing_id,
      bool is_loading,
      blink.mojom.FrameReplicationState new_remote_frame_replication_state,
      blink.mojom.RemoteFrameToken new_remote_frame_token,
      RemoteMainFrameInterfaces new_remote_main_frame_interfaces);

  // Causes all new subresource requests to be blocked (not being started) until
  // ResumeBlockedRequests is called.
  BlockRequests();

  // Resumes blocked requests.
  // It is safe to call this without calling BlockRequests.
  ResumeBlockedRequests();

  GetInterfaceProvider(
      pending_receiver<service_manager.mojom.InterfaceProvider> interfaces);

  // Requests a one-time snapshot of the accessibility tree without enabling
  // accessibility if it wasn't already enabled.
  SnapshotAccessibilityTree(SnapshotAccessibilityTreeParams params)
      => (ax.mojom.AXTreeUpdate snapshot);

  // Get HTML data by serializing the target frame and replacing all resource
  // links with a path to the local copy passed in the message payload. In order
  // to report progress to the the browser process, a pending remote is passed
  // via |callback_remote|, so that direct communication with the SavePackage
  // object that initiated the process can be established.
  GetSerializedHtmlWithLocalLinks(
      map<url.mojom.Url, mojo_base.mojom.FilePath> url_map,
      map<blink.mojom.FrameToken, mojo_base.mojom.FilePath>
          frame_token_map, bool save_with_empty_url,
          pending_remote<FrameHTMLSerializerHandler> handler_remote);
};

// Implemented by the frame (e.g. renderer processes).
// Instances of this interface must be associated with (i.e., FIFO with) the
// legacy IPC channel.
interface FrameBindingsControl {
  // Used to tell a render frame whether it should expose various bindings
  // that allow JS content extended privileges. See BindingsPolicy for valid
  // flag values.
  AllowBindings(int32 enabled_bindings_flags);

  // Used to tell the RenderFrame to enable Mojo JS bindings, which allows
  // JS code running in the renderer process to connect to Mojo interfaces
  // and make method calls on them.
  // This is used for WebUI only at this time.
  EnableMojoJsBindings();

  // Used to enable MojoJS bindings, exposing only the interfaces provided
  // by `broker`.
  EnableMojoJsBindingsWithBroker(
    pending_remote<blink.mojom.BrowserInterfaceBroker> broker);

  // Used to bind WebUI and WebUIHost mojo connections.
  BindWebUI(pending_associated_receiver<content.mojom.WebUI> receiver,
            pending_associated_remote<content.mojom.WebUIHost> remote);
};

struct CreateNewWindowParams {
  // True if ContentRendererClient allows popups.  This is the case only for
  // extensions.
  bool allow_popup;

  // Type of window requested.
  WindowContainerType window_container_type;

  // The session storage namespace ID this window should use.
  string session_storage_namespace_id;

  // The session storage namespace ID this window should clone from.
  // TODO(dmurph): Remove this once session storage is fully mojo'd, as the
  // clone call happens on a different interface. https://crbug.com/716490
  string clone_from_session_storage_namespace_id;

  // The name of the resulting frame that should be created (empty if none
  // has been specified). UTF8 encoded string.
  string frame_name;

  // Whether the opener will be suppressed in the new window, in which case
  // scripting the new window is not allowed.
  bool opener_suppressed;

  // Whether the window should be opened in the foreground, background, etc.
  ui.mojom.WindowOpenDisposition disposition;

  // The URL that will be loaded in the new window (empty if none has been
  // specified).
  url.mojom.Url target_url;

  // The referrer that will be used to load |target_url| (empty if none has
  // been specified).
  blink.mojom.Referrer referrer;

  // The window features to use for the new window.
  blink.mojom.WindowFeatures features;

  // The impression associated with the navigation in the new window, if
  // one is specified.
  blink.mojom.Impression? impression;

  // Governs how downloads are handled if `target_url` results in a download.
  blink.mojom.NavigationDownloadPolicy download_policy;
};

// Operation result when the renderer asks the browser to create a new window.
enum CreateNewWindowStatus {
  // Ignore creation of the new window. This can happen because creation is
  // blocked or because the new window should have no opener relationship.
  kIgnore,
  // Reuse the current window rather than creating a new window.
  kReuse,
  // Create a new window using the corresponding params in |reply|.
  kSuccess,
};

// All routing IDs in this struct must be set to a valid routing ID.
// TODO(dcheng): It's almost possible to use CreateLocalMainFrameParams here.
// See if there's a reasonable way to factor out state here by splitting things
// into browser-created params vs renderer-created params.
struct CreateNewWindowReply {
  // The ID of the view to be created.
  int32 route_id;

  // The unique identifier of the RenderFrameHost
  blink.mojom.LocalFrameToken main_frame_token;

  // The ID of the main frame hosted in the view.
  int32 main_frame_route_id;

  // The pending mojo connection to the Frame implementation in the renderer.
  pending_associated_receiver<content.mojom.Frame> frame;

  CreateFrameWidgetParams widget_params;

  // The communication interfaces for the PageBroadcast.
  pending_associated_receiver<blink.mojom.PageBroadcast> page_broadcast;

  pending_remote<blink.mojom.BrowserInterfaceBroker>
      main_frame_interface_broker;

  // Duplicated from CreateNewWindowParams because legacy code.
  string cloned_session_storage_namespace_id;

  // Used for devtools instrumentation and trace-ability. The token is shared
  // across all frames (local or remotes) representing the same logical frame
  // tree node, and is used by Blink and content to tag calls and requests for
  // instrumentation purposes, allowing them to be attributed to a context
  // frame.
  //
  // Must not be used to look up a RenderFrameHostImpl or RenderFrameProxyHost
  // in the browser process, as the token is shared, making the mapping
  // ambiguous and non-authoritative.
  mojo_base.mojom.UnguessableToken devtools_main_frame_token;

  // Used by devtools instrumentation to tell devtools agent in the renderer
  // that it should pause created window and wait for an explicit resume command
  // from the client.
  bool wait_for_debugger;

  // The policy container for the new frame that will be created by Blink in
  // response.
  blink.mojom.PolicyContainer policy_container;
};

// Implemented by the frame server (i.e. the browser process). For messages that
// must be associated with the IPC channel.
interface FrameHost {
  // Sent by the renderer to request the browser to create a new window. |reply|
  // is only non-null on when status == CreateNewWindowStatus::kSuccess.
  [Sync] CreateNewWindow(CreateNewWindowParams params)
      => (CreateNewWindowStatus status, CreateNewWindowReply? reply);

  // Sent by the renderer process to request the creation of a new portal.
  // |portal| is the pipe to be used for the Portal object, |client| is the pipe
  // used to communicate back with the caller. Returns:
  // |proxy_routing_id| - the routing id of the RenderFrameProxy
  // |initial_replicated_state| - the replicated state associated with that
  //                              RenderFrameProxy
  // |portal_token| - the unique identifier for the portal
  // |frame_token| - the unique identifier of the RenderFrameProxy
  // |devtools_frame_token| - the unique identifier of the frame node in the
  //                          frame tree
  [Sync] CreatePortal(
      pending_associated_receiver<blink.mojom.Portal> portal,
      pending_associated_remote<blink.mojom.PortalClient> client)
      => (int32 proxy_routing_id,
          blink.mojom.FrameReplicationState initial_replicated_state,
          blink.mojom.PortalToken portal_token,
          blink.mojom.RemoteFrameToken frame_token,
          mojo_base.mojom.UnguessableToken devtools_frame_token);

  // Requests that this frame adopts the portal identified by |portal_token|.
  // Returns:
  // |proxy_routing_id| - the routing id of the portal's RenderFrameProxy
  // |replicated_state| - the replicated state associated with that
  //                      RenderFrameProxy
  // |frame_token| - the unique identifier of the RenderFrameProxy
  // |devtools_frame_token| - the unique identifier of the frame node in the
  //                          frame tree
  [Sync] AdoptPortal(blink.mojom.PortalToken portal_token)
      => (int32 proxy_routing_id,
          blink.mojom.FrameReplicationState replicated_state,
          blink.mojom.RemoteFrameToken frame_token,
          mojo_base.mojom.UnguessableToken devtools_frame_token);

  // Sent by the frame in a renderer process that hosts/owns a <fencedframe>
  // element, to the browser process requesting the creation of a new fenced
  // frame tree that will host the contents of the <fencedframe> element.
  // `fenced_frame` - the receiver that the browser will bind to receive
  //                  messages from the renderer.
  // `proxy_routing_id` - the routing ID assigned to the RenderFrameProxy
  //                      placeholder in the owner process.
  // `initial_replication_state` - the replicated state associated with the
  //                               above RenderFrameProxy. This state is
  //                               default-constructed, and thus has an opaque
  //                               origin. This ensures that the origin that the
  //                               proxy host is initialized with in the browser
  //                               and renderer processes both match. For more
  //                               info about this parameter see
  //                               crbug.com/1028269.
  // `frame_token` - the unique identifier of the RenderFrameProxy
  // `devtools_frame_token` - the unique identifier of the main FrameTreeNode in
  //                          the "inner" fenced frame FrameTree
  [Sync] CreateFencedFrame(
      pending_associated_receiver<blink.mojom.FencedFrameOwnerHost>
        fenced_frame)
      => (int32 proxy_routing_id,
          blink.mojom.FrameReplicationState initial_replication_state,
          blink.mojom.RemoteFrameToken frame_token,
          mojo_base.mojom.UnguessableToken devtools_frame_token);

  // Asynchronously creates a child frame. A routing ID must be allocated first
  // by calling RenderMessageFilter::GenerateFrameRoutingID()
  // Each of these messages will have a corresponding mojom::FrameHost::Detach
  // API sent when the frame is detached from the DOM.
  CreateChildFrame(int32 child_routing_id,
                   pending_associated_remote<content.mojom.Frame> frame,
                   pending_receiver<blink.mojom.BrowserInterfaceBroker>
                     browser_interface_broker,
                   blink.mojom.PolicyContainerBindParams
                     policy_container_bind_params,
                   blink.mojom.TreeScopeType scope,
                   string frame_name,
                   string frame_unique_name,
                   bool is_created_by_script,
                   blink.mojom.FramePolicy frame_policy,
                   blink.mojom.FrameOwnerProperties frame_owner_properties,
                   ChildFrameOwnerElementType child_frame_owner_element_type);

  // Sent by the renderer when a navigation commits in the frame.

  // If |interface_params| is non-empty, the FrameHost implementation
  // must unbind the old BrowserInterfaceBroker connections, and drop any
  // interface requests pending on them. Then it should bind the appropriate
  // requests and start servicing GetInterface messages coming in on these new
  // connections in a security context that is appropriate for the committed
  // navigation.
  //
  // The FrameHost implementation must enforce that |interface_params|
  // is set for cross-document navigations. This prevents origin confusion by
  // ensuring that interface requests racing with navigation commit will be
  // either ignored, or serviced correctly in the security context of the
  // document they originated from (based on which BrowserInterfaceBroker
  // connection the GetInterface messages arrive on).
  DidCommitProvisionalLoad(
      DidCommitProvisionalLoadParams params,
      DidCommitProvisionalLoadInterfaceParams? interface_params);

  // Sent by the renderer to indicate that a same document navigation
  // committed in the renderer process.
  DidCommitSameDocumentNavigation(
      DidCommitProvisionalLoadParams params,
      DidCommitSameDocumentNavigationParams same_document_params);

  // Sent by the renderer to indicate that the document input stream has
  // been updated using document.open() and that the URL for the current
  // document in the frame should be updated to `url` per step 12 of
  // https://whatwg.org/C/dynamic-markup-insertion.html#document-open-steps.
  DidOpenDocumentInputStream(url.mojom.Url url);

  // Sent by the renderer to request a navigation.
  // |blob_url_token| should be non-null when this is a navigation to a blob:
  // URL. The token will then be used to look up the blob associated with the
  // blob URL. Without this by the time the navigation code starts fetching
  // the URL the blob URL might no longer be valid. |blob_url_token| is
  // not part of BeginNavigationParams because that struct needs to be
  // cloneable, and thus can't contain mojo interfaces.
  // If an invalid BlobURLToken is passed in, or if the token doesn't match the
  // url in |common_params|, the navigation will result in a network error.
  // |navigation_client| is passed to the renderer to allow for further control
  // of the navigation. Allows for Commit and Cancels/Aborts.
  // Passing the |initiator_policy_container_keep_alive_handle| is just a means
  // to ensure that the PolicyContainerHost of the initiator RenderFrameHost is
  // kept alive, even if the RenderFrameHost itself has already been deleted in
  // the meantime. If this can be ensured in other ways, it is safe to pass a
  // mojo::NullRemote. In particular, if the initiator LocalFrame is alive when
  // issuing this mojo call, there is no need to pass
  // |initiator_policy_container_keep_alive_handle|, since the initiator
  // PolicyContainerHost is kept alive by LocalFrame's PolicyContainer.
  // TODO(ahemery): |navigation_client| should not be optional. Make it
  // mandatory.
  BeginNavigation(
      blink.mojom.CommonNavigationParams common_params,
      blink.mojom.BeginNavigationParams begin_params,
      pending_remote<blink.mojom.BlobURLToken>? blob_url_token,
      pending_associated_remote<NavigationClient>? navigation_client,
      pending_remote<blink.mojom.PolicyContainerHostKeepAliveHandle>?
          initiator_policy_container_keep_alive_handle);

  // Sent when a subresource response has started.
  // |cert_status| is the bitmask of status info of the SSL certificate. (see
  // net/cert/cert_status_flags.h).
  SubresourceResponseStarted(url.mojom.Url url, uint32 cert_status);

  // Sent when a resource load finished, successfully or not.
  ResourceLoadComplete(blink.mojom.ResourceLoadInfo url_load_info);

  // Sent when the frame changes its window.name.
  DidChangeName(string name, string unique_name);

  // If a cross-process navigation was started for the initial history load in
  // this subframe, this tries to cancel it to allow a client redirect to happen
  // instead.
  CancelInitialHistoryLoad();

  // Change the encoding name of the page in UI when the page has detected
  // proper encoding name. Sent for top-level frames.
  UpdateEncoding(string encoding_name);

  // Updates information to determine whether a user gesture should carryover to
  // future navigations. This is needed so navigations within a certain
  // timeframe of a request initiated by a gesture will be treated as if they
  // were initiated by a gesture too, otherwise the navigation may be blocked.
  [EnableIf=is_android]
  UpdateUserGestureCarryoverInfo();

  // Notifies the browser that this frame has new session history information.
  //
  // NOTE: PageState can be quite large when serialized, and its message
  // structure must remain stable; hence [UnlimitedSize] for this message.
  [UnlimitedSize]
  UpdateState(PageState state);

  // Requests that the given URL be opened in the specified manner.
  OpenURL(blink.mojom.OpenURLParams params);

  // Called when the renderer is done loading a frame.
  DidStopLoading();
};