// Copyright 2017 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 "ui/gfx/geometry/mojo/geometry.mojom";

// Provides extra capabilities required for DevTools frontend to function.
// This includes communication channel from/to inspected target which implements
// remote debugging protocol. Protocol messages go through browser process.
// This interface is implemented in DevTools renderer.
//
// Instances of this interface must be associated with navigation-related
// interface, since we should setup DevToolsFrontend before the navigation
// commits in the frame.
interface DevToolsFrontend {
  // Sets up a main frame as a DevTools frontend. This exposes DevToolsHost
  // object (see DevToolsHost.idl for details). The |api_script| is executed
  // on each navigation in the frame before the DevTools frontend starts
  // loading. It makes use of DevToolsHost to expose embedder capabilities to
  // DevTools (e.g. connection to the inspected target).
  SetupDevToolsFrontend(string api_script,
                        associated DevToolsFrontendHost host);

  // Sets up a child frame to expose DevTools extension API by executing script
  // |extension_api| on each navigation in the frame. This script provides
  // required capabilities for DevTools extensions to function, implementing
  // chrome.devtools extension API.
  SetupDevToolsExtensionAPI(string extension_api);
};

// Provides embedder functionality to a frame serving as DevTools frontend.
// This interface is implemented in browser.
interface DevToolsFrontendHost {
  // Sends a message to DevTools frontend embedder.
  DispatchEmbedderMessage(string message);
};


// Used to send large messages in chunks from session to a host.
struct DevToolsMessageChunk {
  // Whether this is a first chunk in a message.
  bool is_first;

  // Whether this is a last chunk in a message.
  bool is_last;

  // The total size of the message being sent in chunks, only comes in
  // a first chunk.
  uint32 message_size;

  // Chunk data.
  string data;

  // Call id as defined in DevTools protocol, only comes for responses.
  int32 call_id;

  // State for future reattach, only comes for responses in a last chunk.
  string post_state;
};

// Implemented by debugging targets which expose remote debugging protocol.
// Examples are local frame roots and service workers.
//
// Note that frame instances of this interface must be associated with
// navigation-related interface, since we should reattach sessions before
// the navigation commits in the frame.
//
// This interface is implemented in renderer hosting entity under debug.
interface DevToolsAgent {
  // Attaches a new debugging session. This session speaks remote debugging
  // protocol and restores all the changes to original state once destroyed.
  //
  // Associated |session| receives messages on UI thread and guarantees
  // relative ordering with e.g. navigations.
  //
  // Non-associated |io_session| receives messages on IO thread and may
  // interrupt long running JavaScript on the main thread. It should be used
  // for debugging messages which are intended to interrupt execution,
  // e.g. requesting a pause. There is no ordering guarantee relative to
  // regular |session|.
  //
  // If |reattach_state| is present, restores the state of the session to
  // previously saved one (see DevToolsMessageChunk). This is useful when
  // transferring a session from one agent to another while preserving the
  // state. For example, cross-process navigation in a frame creates a new
  // DevToolsAgent (in a different process), but we can preserve the state of
  // debugging session by copying it from one agent to another.
  //
  // ------ Why separate sessions? ------
  //
  // To guarantee ordering with legacy IPC channel, we must bind session
  // synchronously on the UI thread. Otherwise there is a time window
  // when the request is not yet bound, but the messages may already come.
  // In this case, messages will be sent to UI hoping that interface
  // is bound there, and get incorrectly dispatched.
  //
  // On the other hand, we need to handle some of the messages on IO without
  // going to UI first (as described above). This means an interface bound
  // on IO thread. Thus a session per thread.
  AttachDevToolsSession(associated DevToolsSessionHost host,
                        associated DevToolsSession& session,
                        DevToolsSession& io_session,
                        string? reattach_state);
};

// Represents an attached session which exposes remote debugging protocol.
// This interface is implemented in renderer hosting entity under debug.
interface DevToolsSession {
  // Dispatches protocol message from a client to a debugging target.
  // |method| is a method name as defined in protocol (e.g. "Runtime.evaluate").
  // |call_id| is a command id as defined in protocol, and is going to be
  // reported back to host in a response message (see DevToolsMessageChunk).
  DispatchProtocolMessage(int32 call_id, string method, string message);

  // Requests an element at specific position to be inspected.
  InspectElement(gfx.mojom.Point point);
};

// A peer of DevToolsSession representing a remote debugging client
// which receives notifications and responses from a session.
// This interface is implemented in browser.
interface DevToolsSessionHost {
  // Dispatches protocol message (in chunks) to a remote debugging client.
  DispatchProtocolMessage(DevToolsMessageChunk chunk);

  // Requests a new DevTools window for a frame with given routing id.
  // TODO(dgozman): get rid of routing id when possible.
  RequestNewWindow(int32 frame_routing_id) => (bool success);
};