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

module extensions.mojom;

import "mojo/public/mojom/base/uuid.mojom";
import "extensions/common/mojom/code_injection.mojom";
import "extensions/common/mojom/context_type.mojom";
import "extensions/common/mojom/extra_response_data.mojom";
import "extensions/common/mojom/host_id.mojom";
import "extensions/common/mojom/injection_type.mojom";
import "extensions/common/mojom/extension_id.mojom";
import "extensions/common/mojom/match_origin_as_fallback.mojom";
import "extensions/common/mojom/message_port.mojom";
import "extensions/common/mojom/run_location.mojom";
import "extensions/common/mojom/stack_frame.mojom";
import "extensions/common/mojom/view_type.mojom";
import "mojo/public/mojom/base/string16.mojom";
import "mojo/public/mojom/base/values.mojom";
import "ui/gfx/geometry/mojom/geometry.mojom";
import "url/mojom/url.mojom";
import "third_party/blink/public/mojom/devtools/console_message.mojom";

// Allows an extension to execute code in a tab.
struct ExecuteCodeParams {
  // The ID of the requesting injection host.
  HostID host_id;

  // The CSS or JS to inject into the target.
  CodeInjection injection;

  // The webview guest source who calls to execute code.
  url.mojom.Url webview_src;
  // Behavior for frames where the URL cannot be matched directly.
  MatchOriginAsFallbackBehavior match_origin_as_fallback_behavior;
  // When to inject the code.
  RunLocation run_at;
  // Whether the request is coming from a <webview>.
  bool is_web_view;
};

// Parameters structure for LocalFrameHost.Request().
struct RequestParams {
  // Message name.
  string name;
  // List of message arguments.
  mojo_base.mojom.ListValue arguments;
  // Extension ID this request was sent from. This can be empty, in the case
  // where we expose APIs to normal web pages using the extension function
  // system.
  // TODO(crbug.com/404555668): Convert to extensions::mojom::ExtensionId.
  string extension_id;
  // URL of the frame the request was sent from. This isn't necessarily an
  // extension url. Extension requests can also originate from content scripts,
  // in which case extension_id will indicate the ID of the associated
  // extension. Or, they can originate from hosted apps or normal web pages.
  url.mojom.Url source_url;
  // The context type associated with the sender. Note that this is *not* to
  // be treated as a security boundary (since it might come from a compromised
  // renderer), but can be used to differentiate between different types of
  // contexts within the same renderer (e.g. content script vs web page).
  ContextType context_type;
  // Unique request id to match requests and responses.
  int32 request_id;
  // True if request has a callback specified.
  bool has_callback;
  // True if request is executed in response to an explicit user gesture.
  bool user_gesture;
  // If this API call is for a service worker, then this is the worker thread
  // id. Otherwise, this is kMainThreadId.
  int32 worker_thread_id;
  // If this API call is for a service worker, then this is the service
  // worker version id. Otherwise, this is set to
  // blink::mojom::kInvalidServiceWorkerVersionId.
  int64 service_worker_version_id;
  // Contains the JS call stack when an extension API method is invoked.
  // This field is collected for telemetry purposes only and is only populated
  // for a subset of extension API (for e.g., some chrome.tabs API methods).
  // For all other API methods, this field is empty.
  array<StackFrame>? js_callstack;
};

// Implemented in the renderer, this interface defines the local frame specific
// methods.
interface LocalFrame {
  // Sets the top-level frame to the provided name.
  SetFrameName(string frame_name);

  // Enables or disables spatial navigation.
  SetSpatialNavigationEnabled(bool spatial_nav_enabled);

  // Tells the render view what its tab ID is.
  SetTabId(int32 tab_id);

  // Notifies the renderer that its window has closed.
  AppWindowClosed(bool send_onclosed);

  // Tells the renderer which type this view is.
  NotifyRenderViewType(ViewType view_type);

  // Asks the renderer to invoke |function_name| with |args| in |module_name|.
  // If |extension_id| is non-empty, the function will be invoked only in
  // contexts owned by the extension. |args| is a list of primitive Value types
  // that are passed to the function.
  MessageInvoke(ExtensionId extension_id,
                string module_name,
                string function_name,
                mojo_base.mojom.ListValue args);

  // Notifies the renderer that it should run some JavaScript code. The reply
  // is sent back to the browser to return the script running result. An empty
  // |error| implies success. |url| is the URL that the code executed on. It may
  // be empty if it's unsuccessful. We use an optional for |result| to
  // differentiate between no result (such as in the case of an error) and a
  // null result.
  ExecuteCode(ExecuteCodeParams param) =>
      (string error, url.mojom.Url url, mojo_base.mojom.Value? result);

  // Trigger to execute declarative content script under browser control.
  ExecuteDeclarativeScript(int32 tab_id,
                           ExtensionId extension_id,
                           string script_id,
                           url.mojom.Url url);

  // Tell the render view which browser window it's being attached to.
  UpdateBrowserWindowId(int32 window_id);

  // Dispatch the Port.onConnect event for message channels.
  DispatchOnConnect(
    extensions.mojom.PortId port_id,
    extensions.mojom.ChannelType channel_type,
    string channel_name,
    extensions.mojom.TabConnectionInfo tab_info,
    extensions.mojom.ExternalConnectionInfo external_connection_info,
    pending_associated_receiver<extensions.mojom.MessagePort> port,
    pending_associated_remote<extensions.mojom.MessagePortHost> port_host) =>
    (bool success);
};

// Implemented in the browser, this interface defines the local frame host
// specific methods.
interface LocalFrameHost {
  // Requests permission for a script injection from the renderer to the
  // browser.
  // The reply is sent back to the renderer with |granted| for granting
  // permission for a script to run. If |granted| is false, the permission
  // should not be handled.
  RequestScriptInjectionPermission(ExtensionId extension_id,
                      InjectionType script_type,
                      RunLocation run_location) => (bool granted);

  // Gets the install state for the app when a web page is checking if its app
  // is installed. The reply is sent back to the renderer with |state|.
  GetAppInstallState(url.mojom.Url url) => (string state);

  // Sends an extension API request to the browser.
  // The reply is sent back to the renderer with the response data (if any) is
  // one of the base::Value types, wrapped as the first element in a LIST
  // typed Value.
  [UnlimitedSize]
  Request(RequestParams params)
      => (bool success,
          mojo_base.mojom.ListValue response_wrapper,
          string error,
          ExtraResponseData? extra_data);

  // An "ack" sent from the renderer that it received the response.
  // This is only sent for certain API functions (where the browser needs to
  // know the renderer received the response).
  ResponseAck(mojo_base.mojom.Uuid request_uuid);

  // Notifies the browser process that a tab has started or stopped matching
  // certain conditions.  This method is called by response to several events:
  //
  // * The WatchPages Mojo method was called, updating the set of
  // * conditions. A new page is loaded.  This will be invoked after
  //   mojom::FrameHost::DidCommitProvisionalLoad. Currently this only fires for
  //   the main frame.
  // * Something changed on an existing frame causing the set of matching
  //   searches to change.
  WatchedPageChange(array<string> css_selectors);

  // Tells listeners that a detailed message was reported to the console.
  DetailedConsoleMessageAdded(mojo_base.mojom.String16 message,
                              mojo_base.mojom.String16 source,
                              array<StackFrame> stack_trace,
                              blink.mojom.ConsoleMessageLevel level);

  // Notifies the browser that content scripts are running in the renderer
  // that the IPC originated from.
  ContentScriptsExecuting(map<string, array<string>> extension_id_to_scripts,
                          url.mojom.Url frame_url);

  // Informs the browser to increment the keepalive count for the lazy
  // background page, keeping it alive.
  IncrementLazyKeepaliveCount();

  // Informs the browser there is one less thing keeping the lazy background
  // page alive.
  DecrementLazyKeepaliveCount();

  // Notify the browser that an app window is ready and can resume resource
  // requests.
  AppWindowReady();

  // Open a channel to all listening contexts owned by the extension with
  // the given ID.
  OpenChannelToExtension(
    extensions.mojom.ExternalConnectionInfo info,
    extensions.mojom.ChannelType channel_type,
    string channel_name, extensions.mojom.PortId port_id,
    pending_associated_remote<extensions.mojom.MessagePort> port,
    pending_associated_receiver<extensions.mojom.MessagePortHost> port_host);

  // Get a port handle to the native application.  The handle can be used for
  // sending messages to the extension.
  // `android_certificates` specifies the list of expected signing certificates
  // if `native_app_name` is an external Android app.
  OpenChannelToNativeApp(
    string native_app_name,
    [EnableIf=is_android]
    array<array<uint8, 32>> android_certificates,
    extensions.mojom.PortId port_id,
    pending_associated_remote<extensions.mojom.MessagePort> port,
    pending_associated_receiver<extensions.mojom.MessagePortHost> port_host);

  // Get a port handle to the given tab.  The handle can be used for sending
  // messages to the extension.
  OpenChannelToTab(
    int32 tab_id, int32 frame_id, string? document_id,
    extensions.mojom.ChannelType channel_type,
    string channel_name, extensions.mojom.PortId port_id,
    pending_associated_remote<extensions.mojom.MessagePort> port,
    pending_associated_receiver<extensions.mojom.MessagePortHost> port_host);
};