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 "content/common/document_scoped_interface_bundle.mojom";
import "content/common/frame_messages.mojom";
import "content/common/native_types.mojom";
import "content/common/navigation_client.mojom";
import "content/common/navigation_params.mojom";
import "content/common/web_ui.mojom";
import "content/public/common/browser_controls_state.mojom";
import "content/public/common/window_container_type.mojom";
import "mojo/public/mojom/base/file_path.mojom";
import "mojo/public/mojom/base/string16.mojom";
import "mojo/public/mojom/base/unguessable_token.mojom";
import "mojo/public/mojom/base/values.mojom";
import "services/network/public/mojom/content_security_policy.mojom";
import "services/network/public/mojom/web_sandbox_flags.mojom";
import "services/network/public/mojom/url_loader.mojom";
import "services/network/public/mojom/url_loader_factory.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/frame_sink_id.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/devtools/console_message.mojom";
import "third_party/blink/public/mojom/devtools/devtools_agent.mojom";
import "third_party/blink/public/mojom/feature_policy/document_policy_feature.mojom";
import "third_party/blink/public/mojom/feature_policy/feature_policy.mojom";
import "third_party/blink/public/mojom/feature_policy/feature_policy_feature.mojom";
import "third_party/blink/public/mojom/feature_policy/policy_value.mojom";
import "third_party/blink/public/mojom/frame/frame_owner_element_type.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/lifecycle.mojom";
import "third_party/blink/public/mojom/frame/navigation_initiator.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/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/page/page.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/loader/referrer.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/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;

// The name of the InterfaceProviderSpec in service manifests used by the
// frame tree to expose frame-specific interfaces between renderer and browser.
const string kNavigation_FrameSpec = "navigation: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();
};

// Implemented by the frame provider (e.g. renderer processes).
interface Frame {
  GetInterfaceProvider(
      pending_receiver<service_manager.mojom.InterfaceProvider> interfaces);
  GetCanonicalUrlForSharing() => (url.mojom.Url? canonical_url);

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

  // Samsung Galaxy Note-specific "smart clip" stylus text getter.
  // Extracts the data at the given rect.
  [EnableIf=is_android]
  ExtractSmartClipData(gfx.mojom.Rect rect)
      => (mojo_base.mojom.String16 text, mojo_base.mojom.String16 html,
              gfx.mojom.Rect clip_rect);

  // Notifies the renderer whether hiding/showing the browser controls is
  // enabled, what the current state should be, and whether or not to
  // animate to the proper state.
  UpdateBrowserControlsState(BrowserControlsState constraints,
                             BrowserControlsState current,
                             bool animate);

  // Requests a one-time snapshot of the accessibility tree without enabling
  // accessibility if it wasn't already enabled.
  // See ui/accessibility/ax_mode.h for valid values of |ax_mode|.
  //
  // TODO(crbug.com/1141990): AXTreeUpdate can be quite large, hence the
  // [UnlimitedSize] tag. It may be possible to remove this if AXTreeUpdate
  // can be reworked to avoid very large serialized values.
  SnapshotAccessibilityTree(uint32 ax_mode)
      => (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<mojo_base.mojom.UnguessableToken, mojo_base.mojom.FilePath>
          frame_token_map, bool save_with_empty_url,
          pending_remote<FrameHTMLSerializerHandler> handler_remote);
};

// Implemented by the frame provider and currently must be associated with the
// legacy IPC channel.
// KEEP THE COMMIT FUNCTIONS IN SYNC in content/common/navigation_client.mojom.
// These will eventually be removed from FrameNavigationControl.
interface FrameNavigationControl {
  // 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(
      CommonNavigationParams common_params,
      CommitNavigationParams request_params)
      => (blink.mojom.CommitResult commit_result);

  // Asks the renderer to handle a renderer-debug URL.
  HandleRendererDebugURL(url.mojom.Url url);

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

  // Returns a DevToolsAgent interface for this frame, used for
  // remote debugging. See DevToolsAgent for details.
  // Returned DevToolsAgent must be associated with navigation control,
  // due to various ordering dependencies between DevTools protocol and
  // navigation.
  BindDevToolsAgent(
      pending_associated_remote<blink.mojom.DevToolsAgentHost> agent_host,
      pending_associated_receiver<blink.mojom.DevToolsAgent> agent);

  // Request for the renderer to execute a given JavaScript method on a given
  // object (both identified by name) in the frame's context.
  //
  // |object_name| is the global name of the object.
  //
  // |method_name| is the name of the method on the object.
  //
  // |arguments| is the list of arguments to pass to the method invocation.
  //
  // |wants_result| is true if the result of this execution is required by the
  // caller. If it is false, a reply is still required by Mojo, but a null value
  // should be returned to avoid issues serializing a large, unwanted reply.
  JavaScriptMethodExecuteRequest(
      mojo_base.mojom.String16 object_name,
      mojo_base.mojom.String16 method_name,
      mojo_base.mojom.ListValue arguments,
      bool wants_result) => (mojo_base.mojom.Value result);

  // Request for the renderer to execute JavaScript in the frame's context.
  //
  // |javascript| is the string containing the JavaScript to be executed in the
  // target frame's context. Note that this uses BigString16 rather than
  // String16 as this is used in contexts, like DevTools, where the contents of
  // the JavaScript script is user-provided, and therefore we can't guarantee
  // the size of the script.
  //
  // |wants_result| is true if the result of this execution is required by the
  // caller. If it is false, a reply is still required by Mojo, but a null value
  // should be returned to avoid issues serializing a large, unwanted reply.
  //
  // TODO(hajimehoshi): This requires navigate association to keep the message
  // order with other navigation-related messages. Fix this and move this to a
  // non-navigate-related interface if possible.
  JavaScriptExecuteRequest(
      mojo_base.mojom.BigString16 javascript,
      bool wants_result) => (mojo_base.mojom.Value result);

  // ONLY FOR TESTS: Same as above but this can optionally trigger a fake user
  // activation notification to test functionalities that are gated by user
  // activation.
  JavaScriptExecuteRequestForTests(
      mojo_base.mojom.BigString16 javascript,
      bool wants_result,
      bool has_user_gesture,
      int32 world_id)
      => (mojo_base.mojom.Value result);

  // Same as JavaScriptExecuteRequest above except the script is run in the
  // isolated world specified by the fourth parameter.
  JavaScriptExecuteRequestInIsolatedWorld(
      mojo_base.mojom.BigString16 javascript,
      bool wants_result,
      int32 world_id) => (mojo_base.mojom.Value result);

  // Requests that a provisional RenderFrame swap itself into the frame tree,
  // replacing the RenderFrameProxy that it is associated with. This is used
  // with remote-to-local frame navigations when the RenderFrameProxy
  // corresponds to a non-live (crashed) frame. In that case, the browser
  // process will send this message as part of an early commit to stop showing
  // the sad iframe without waiting for the provisional RenderFrame's navigation
  // to commit.
  SwapIn();
};

// 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 bind WebUI and WebUIHost mojo connections.
  BindWebUI(pending_receiver<content.mojom.WebUI> receiver,
            pending_remote<content.mojom.WebUIHost> remote);
};

// Implemented by a service that provides implementations of the Frame
// interface. (e.g. renderer processes).
interface FrameFactory {
  CreateFrame(int32 frame_routing_id, pending_receiver<Frame> frame);
};

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;
};

// 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.
struct CreateNewWindowReply {
  // The ID of the view to be created.
  int32 route_id;

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

  // The unique identifier of the RenderFrameHost
  mojo_base.mojom.UnguessableToken main_frame_frame_token;

  // The ID of the widget for the main frame.
  int32 main_frame_widget_route_id;

  // Initial properties for the main frame RenderWidget.
  blink.mojom.VisualProperties visual_properties;

  // 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 communication interfaces for the PageBroadcast.
  pending_associated_receiver<blink.mojom.PageBroadcast> page_broadcast;

  DocumentScopedInterfaceBundle main_frame_interface_bundle;

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

  // 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_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;
};

[Native]
enum TriggeringEventInfo;

// This struct holds parameters included in the OpenURL method sent by the
// renderer to the browser, |is_history_navigation_in_new_child_frame| is true
// in the case that the browser process should look for an existing history item
// for the frame.
struct OpenURLParams {
  // The main URL to open.
  url.mojom.Url url;
  url.mojom.Origin initiator_origin;
  int32 initiator_routing_id;
  network.mojom.URLRequestBody? post_body;
  string extra_headers;
  blink.mojom.Referrer referrer;

  // The window position to open the URL.
  ui.mojom.WindowOpenDisposition disposition;
  bool should_replace_current_entry;
  bool user_gesture;

  // Extra information about the triggering of the OpenURL.
  TriggeringEventInfo triggering_event_info;
  handle<message_pipe>? blob_url_token;
  string href_translate;
  Impression? impression;
  NavigationDownloadPolicy download_policy;
};

// An opaque handle that keeps alive the associated render process even after
// the frame is detached. Used by resource requests with "keepalive" specified.
interface KeepAliveHandle {};

// 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,
          FrameReplicationState initial_replicated_state,
          blink.mojom.PortalToken portal_token,
          mojo_base.mojom.UnguessableToken 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,
          viz.mojom.FrameSinkId frame_sink_id,
          FrameReplicationState replicated_state,
          mojo_base.mojom.UnguessableToken frame_token,
          mojo_base.mojom.UnguessableToken devtools_frame_token);


  // Similar to CreateNewWindow, except used for sub-widgets, like <select>
  // dropdowns. Upon return, the renderer side popup will be owned by the
  // PopupWidgetHost.
  CreateNewPopupWidget(
         pending_associated_receiver<blink.mojom.PopupWidgetHost> popup_host,
         pending_associated_receiver<blink.mojom.WidgetHost> blink_widget_host,
         pending_associated_remote<blink.mojom.Widget> blink_widget);

  // 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_receiver<service_manager.mojom.InterfaceProvider>
                     new_interface_provider,
                   pending_receiver<blink.mojom.BrowserInterfaceBroker>
                     browser_interface_broker,
                   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,
                   blink.mojom.FrameOwnerElementType frame_owner_element_type);

  // Creates and returns a KeepAliveHandle.
  IssueKeepAliveHandle(pending_receiver<KeepAliveHandle> keep_alive_handle);

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

  // If |interface_params| is non-empty, the FrameHost implementation
  // must unbind the old InterfaceProvider and 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 InterfaceProvider or
  // 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);

  // 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. It is only valid
  // when PerNavigationMojoInterface is enabled.
  // TODO(ahemery): |navigation_client| should not be optional. Make it
  // mandatory when removing PerNavigationMojoInterface feature flag.
  BeginNavigation(
      CommonNavigationParams common_params,
      BeginNavigationParams begin_params,
      pending_remote<blink.mojom.BlobURLToken>? blob_url_token,
      pending_associated_remote<NavigationClient>? navigation_client,
      pending_remote<blink.mojom.NavigationInitiator>? navigation_initiator);

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

  // Notifies the browser process that HTTP headers which affect the frame
  // polices were delivered with the document being loaded into the frame. This
  // can be any or all of 'Feature-Policy' or 'Content-Security-Policy' (
  // which can set sandbox flags) or 'Document-Policy'.
  //
  // |feature_policy_header| is a list of an origin whitelist for each feature
  // in the policy.
  DidSetFramePolicyHeaders(
      network.mojom.WebSandboxFlags sandbox_flags,
      array<blink.mojom.ParsedFeaturePolicyDeclaration> feature_policy_header,
      map<blink.mojom.DocumentPolicyFeature, blink.mojom.PolicyValue>
        document_policy_header);

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

  // The frame's size is replicated in the browser so that the browser can
  // correctly set the initial size of the frame in case of a cross-process
  // navigation.
  FrameSizeChanged(gfx.mojom.Size size);

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

  // Blink and JavaScript error messages to log to the console or debugger UI.
  DidAddMessageToConsole(
      blink.mojom.ConsoleMessageLevel log_level,
      mojo_base.mojom.BigString16 msg,
      int32 line_number,
      mojo_base.mojom.String16 source_id);

  // 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(OpenURLParams params);

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