// 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 blink.mojom;

import "mojo/public/mojom/base/big_string.mojom";
import "ui/gfx/geometry/mojo/geometry.mojom";

// Debugging interactions are defined in Remote Debugging Protocol.
// See https://chromedevtools.github.io/devtools-protocol/ for more
// information on the protocol itself.
//
// All interfaces defined here serve as a transport level for the
// remote debugging protocol, passing messages opaquely between debugging
// client (like DevTools frontend) and debugging agent (like core/inspector).

// 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.
// Note that this interface just provides a mean to start a debugging session,
// so the presence of it does not mean the entity is under debug just yet.
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_session_state| is present, restores the state of the session
  // to previously saved one (see DevToolsSessionHost). 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.
  //
  // Note that |io_session| is not associated with DevToolsAgent, and so
  // there is no ordering guarantee for commands send to |io_session|
  // relative to anything coming over regular |session|.
  // For example, |session| may be already detached (interface unbound),
  // while commands are still coming to |io_session|, and vice versa.
  AttachDevToolsSession(associated DevToolsSessionHost host,
                        associated DevToolsSession& session,
                        DevToolsSession& io_session,
                        DevToolsSessionState? reattach_session_state);

  // Requests an element at specific position to be inspected in every
  // attached session (or the next attached one if none yet).
  //
  // Note that inspecting element does not start/stop any debugging sessions
  // by itself, and has no effect unless a debugging session is
  // or will be attached.
  InspectElement(gfx.mojom.Point point);
};

// Represents an attached session which exposes remote debugging protocol.
// This interface is implemented in renderer hosting entity under debug.
//
// Lifetime of the session exactly matches the debugging time span. In other
// words, the entity is under debug if and only if there is at least one
// session.
interface DevToolsSession {
  // Dispatches protocol command 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 DevToolsSessionHost).
  DispatchProtocolCommand(int32 call_id, string method, string message);
};

// 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 command response to a remote debugging client.
  // |call_id| is a command id as defined in protocol.
  // |updates| are the session state deltas for future reattach (see
  // DevToolsAgent), may be missing if the state did not change since
  // last time.
  DispatchProtocolResponse(mojo_base.mojom.BigString message,
                           int32 call_id,
                           DevToolsSessionState? updates);

  // Dispatches protocol notification to a remote debugging client.
  DispatchProtocolNotification(mojo_base.mojom.BigString message,
                               DevToolsSessionState? updates);
};

// The session state is a mapping from keys to either values or missing
// values. Missing values are only used when updates are sent; that's
// in DispatchProtocolResponse and DispatchProtocolNotification. The
// DevToolsSession will then interpret these missing values by deleting
// the respective key when its applying the updates in
// DevToolsSession::ApplySessionStateUpdates.
struct DevToolsSessionState {
  map<string, string?> entries;
};