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

module discards.mojom;

import "chrome/browser/resource_coordinator/lifecycle_unit_state.mojom";
import "mojo/public/mojom/base/process_id.mojom";
import "mojo/public/mojom/base/time.mojom";
import "url/mojom/url.mojom";

// Identical to content::Visibility. Sent from browser to the chrome://discards
// WebUI.
enum LifecycleUnitVisibility {
  HIDDEN = 0,
  OCCLUDED = 1,
  VISIBLE = 2,
};

// Whether a tab can be frozen.
enum CanFreeze {
  // All types of freezing are possible for the page.
  YES,
  // Only some types of freezing are possible for the page.
  VARIES,
  // No freezing is possible for the page.
  NO,
};

// Discard related information about a single tab in a browser. Sent from
// browser to the chrome://discards WebUI.
struct TabDiscardsInfo {
  // The URL associated with the tab. This corresponds to GetLastCommittedURL,
  // and is also what is visible in the Omnibox for a given tab.
  string tab_url;
  // The title of the tab, as displayed on the tab itself.
  string title;
  // The visibility of the LifecycleUnit.
  LifecycleUnitVisibility visibility;
  // The loading state of the LifecycleUnit.
  mojom.LifecycleUnitLoadingState loading_state;
  // The state of the LifecycleUnit.
  mojom.LifecycleUnitState state;
  // Whether the tab can be discarded.
  bool can_discard;
  // List of human-readable reasons why a tab can't be discarded.
  array<string> cannot_discard_reasons;
  // Whether the tab can be frozen.
  CanFreeze can_freeze;
  // List of human-readable reasons why a tab can't be frozen.
  array<string> cannot_freeze_reasons;
  // The number of times this tab has been discarded in the current browser
  // session.
  int32 discard_count;
  // If the tab is currently discarded, the discard reason.
  mojom.LifecycleUnitDiscardReason discard_reason;
  // The rank of the tab in the "importance to user" list. The tab with 1 is the
  // most important, the tab with N is the least important.
  int32 utility_rank;
  // The time the tab was last active (foreground in a window), in seconds.
  int32 last_active_seconds;
  // A unique ID for the tab. This is unique for a browser session and follows a
  // tab across tab strip operations, reloads and discards.
  int32 id;
  // Whether or not the tab is eligible for auto-discarding by the browser.
  // This can be manipulated by the chrome://discards UI, or via the discards
  // extension API.
  bool is_auto_discardable;
  // Site engagement score.
  double site_engagement_score;
  // Whether or not the tab has input focus.
  bool has_focus;
  // Delta between Unix Epoch and time at which the lifecycle state has changed.
  mojo_base.mojom.TimeDelta state_change_time;
};

// Interface for providing information about discards. Lives in the browser
// process and is invoked in the renderer process via Javascript code running in
// the chrome://discards WebUI.
interface DetailsProvider {
  // Returns an array of TabDiscardsInfo containing discard information about
  // each tab currently open in the browser, across all profiles.
  GetTabDiscardsInfo() => (array<TabDiscardsInfo> infos);

  // Sets the auto-discardable state of a tab, as specified by its stable
  // |tab_id|, earlier returned by GetTabDiscardsInfo. Invokes a callback when
  // the change has been made.
  SetAutoDiscardable(int32 tab_id, bool is_auto_discardable) => ();

  // Discards a tab given its |tab_id|. The unload handlers will not be run, and
  // the tab will be unloaded with prejudice.
  // Invokes a callback when the discard is complete.
  DiscardById(int32 tab_id, mojom.LifecycleUnitDiscardReason reason) => ();

  // Freezes a tab given its |tab_id|.
  FreezeById(int32 tab_id);

  // Loads a tab given its |tab_id|.
  LoadById(int32 tab_id);

  // Discards the least important tab.
  // This can fail to discard a tab if no tabs are currently considered
  // eligible for discard. Invokes a callback when the discard is complete, or
  // if the decision was made not to discard.
  Discard() => ();

  // Toggle battery saver modes for manual testing.
  // If the mode is enabled, this will disable it. Conversely, if it is disabled
  // this will enable it.
  ToggleBatterySaverMode();

  // Refreshes the tab CPU measurements as if the CPU health tracker queries
  // for tab CPU usage data naturally.
  RefreshPerformanceTabCpuMeasurements();
};

// Represents the momentary state of a Page node. Sent from browser to the
// chrome://discards WebUI via the GraphChangeStream (defined below).
struct PageInfo {
  int64 id;

  url.mojom.Url main_frame_url;

  // The id of the frame that opened this page via window.open, if any.
  int64 opener_frame_id;

  // The id of the frame that embedded this page, if any.
  int64 embedder_frame_id;

  // This field is a dictionary of values, where each value is generated by
  // a performance_manager::NodeDataDescriber implementation and keyed by the
  // name it registered with. The intent is for each describer to describe
  // private node-related or node-attached data in some way, to allow presenting
  // otherwise hidden state in the chrome://discards/graph view.
  string description_json;
};

// Represents the momentary state of a Frame node. Sent from browser to the
// chrome://discards WebUI via the GraphChangeStream (defined below).
struct FrameInfo {
  int64 id;

  // The last committed URL of this frame.
  url.mojom.Url url;

  // The ID of the page node this frame is associated with.
  int64 page_id;

  // The ID of the parent frame, if there is one. If not, this is a main frame.
  int64 parent_frame_id;

  // The ID of the process in which this frame is hosted.
  int64 process_id;

  // See PageInfo::description_json.
  string description_json;
};

// Represents the momentary state of a Process node. Sent from browser to the
// chrome://discards WebUI via the GraphChangeStream (defined below).
struct ProcessInfo {
  int64 id;

  // The PID of the process associated with this node.
  mojo_base.mojom.ProcessId pid;

  // The private memory usage of this process in KB.
  uint64 private_footprint_kb;

  // See PageInfo::description_json.
  string description_json;
};

// Represents the momentary state of a Worker node. Sent from browser to the
// chrome://discards WebUI via the GraphChangeStream (defined below).
struct WorkerInfo {
  int64 id;

  // The URL of the worker.
  url.mojom.Url url;

  // The ID of the process is which this worker is hosted.
  int64 process_id;

  // An array of frames (by ID) that are clients of this worker (the worker is
  // doing work on behalf of this frame). See
  // WorkerNode::GetClientFrames() for details.
  array<int64> client_frame_ids;

  // An array of other workers (by ID) that are clients of this worker (the
  // worker is doing work on behalf of these other workers). See
  // WorkerNode::GetClientWorkers() for details.
  array<int64> client_worker_ids;

  // An array of workers (by ID) that are children of this worker. This can
  // occur with shared and service workers owning their own dedicated workers.
  // See WorkerNode::GetChildWorkers() for details.
  array<int64> child_worker_ids;

  // See PageInfo::description_json.
  string description_json;
};

// Used to transport favicon data. Sent from browser to the chrome://discards
// WebUI via the GraphChangeStream (defined below).
struct FavIconInfo {
  int64 node_id;

  // Contains the base64-encoded icon data, suitable for inclusion in a
  // data URL.
  string icon_data;
};

// Implement to receive a stream of notifications when performance manager
// graph nodes are created, changed or deleted. Implemented in Javascript code
// running in the chrome://discards WebUI, with data routed to it from an
// observer of the performance_manager::Graph in the browser. The implementation
// is injected into the browser via the browser-exposed GraphDump interface,
// defined below.
interface GraphChangeStream {
  // The |frame| was created.
  FrameCreated(FrameInfo frame);
  // The |page| was created.
  PageCreated(PageInfo pages);
  // The |process| was created.
  ProcessCreated(ProcessInfo process);
  // The |worker| was created.
  WorkerCreated(WorkerInfo worker);

  // The |frame| changed.
  FrameChanged(FrameInfo frame);
  // The |page| changed.
  PageChanged(PageInfo page);
  // The |process| changed.
  ProcessChanged(ProcessInfo process);
  // The |worker| was changed.
  WorkerChanged(WorkerInfo worker);

  // A |favicon| became available, whether because the associated page changed
  // its favicon, or because an initial lookup completed.
  FavIconDataAvailable(FavIconInfo favicon);

  // The node with |node_id| was deleted.
  NodeDeleted(int64 node_id);
};

// This interface allows subscribing to a stream of events that track the state
// of the performance manager graph. Implemented in browser code, and used from
// Javascript code running in the chrome://discards WebUI.
interface GraphDump {
  // Subscribes |change_subscriber| to a graph change stream.
  SubscribeToChanges(pending_remote<GraphChangeStream> change_subscriber);

  // Requests the node descriptions for the nodes with IDs |node_ids|. If any
  // ID in |node_ids| is invalid, e.g. is not the ID of an existent node,
  // the result will omit that node ID. The result will also omit nodes that
  // have no description.
  // Each returned description is a dictionary of values, where each value is
  // generated by a performance_manager::NodeDataDescriber implementation and
  // keyed by the name it registered with. The intent is for each describer to
  // describe private node-related or node-attached data in some way, to allow
  // presenting otherwise hidden state in the chrome://discards/graph view.
  RequestNodeDescriptions(array<int64> node_ids) =>
      (map<int64, string> node_descriptions_json);
};